diff options
Diffstat (limited to 'doc/classes')
362 files changed, 9518 insertions, 2030 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 1ae3674f65..3a1bd83c18 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -234,20 +234,9 @@ var b = clamp(8.1, 0.9, 5.5) # b is 5.5 - - var c = clamp(Vector2(-3.5, -4), Vector2(-3.2, -2), Vector2(2, 6.5)) - # c is (-3.2, -2) - - var d = clamp(Vector2i(7, 8), Vector2i(-3, -2), Vector2i(2, 6)) - # d is (2, 6) - - var e = clamp(Vector3(-7, 8.5, -3.8), Vector3(-3, -2, 5.4), Vector3(-2, 6, -4.1)) - # e is (-3, -2, 5.4) - - var f = clamp(Vector3i(-7, -8, -9), Vector3i(-1, 2, 3), Vector3i(-4, -5, -6)) - # f is (-4, -5, -6) [/codeblock] - [b]Note:[/b] For better type safety, use [method clampf], [method clampi], [method Vector2.clamp], [method Vector2i.clamp], [method Vector3.clamp], [method Vector3i.clamp], [method Vector4.clamp], [method Vector4i.clamp], or [method Color.clamp]. + [b]Note:[/b] For better type safety, use [method clampf], [method clampi], [method Vector2.clamp], [method Vector2i.clamp], [method Vector3.clamp], [method Vector3i.clamp], [method Vector4.clamp], [method Vector4i.clamp], or [method Color.clamp] (not currently supported by this method). + [b]Note:[/b] When using this on vectors it will [i]not[/i] perform component-wise clamping, and will pick [param min] if [code]value < min[/code] or [param max] if [code]value > max[/code]. To perform component-wise clamping use the methods listed above. </description> </method> <method name="clampf"> @@ -373,7 +362,7 @@ [/codeblock] </description> </method> - <method name="ease"> + <method name="ease" keywords="smooth"> <return type="float" /> <param index="0" name="x" type="float" /> <param index="1" name="curve" type="float" /> @@ -529,7 +518,7 @@ [/codeblocks] </description> </method> - <method name="inverse_lerp"> + <method name="inverse_lerp" keywords="interpolate"> <return type="float" /> <param index="0" name="from" type="float" /> <param index="1" name="to" type="float" /> @@ -548,7 +537,7 @@ See also [method lerp], which performs the reverse of this operation, and [method remap] to map a continuous series of values to another. </description> </method> - <method name="is_equal_approx"> + <method name="is_equal_approx" keywords="roughly"> <return type="bool" /> <param index="0" name="a" type="float" /> <param index="1" name="b" type="float" /> @@ -626,7 +615,7 @@ This function is faster than using [method is_equal_approx] with one value as zero. </description> </method> - <method name="lerp"> + <method name="lerp" keywords="interpolate"> <return type="Variant" /> <param index="0" name="from" type="Variant" /> <param index="1" name="to" type="Variant" /> @@ -641,7 +630,7 @@ [b]Note:[/b] For better type safety, use [method lerpf], [method Vector2.lerp], [method Vector3.lerp], [method Vector4.lerp], [method Color.lerp], [method Quaternion.slerp] or [method Basis.slerp]. </description> </method> - <method name="lerp_angle"> + <method name="lerp_angle" keywords="interpolate"> <return type="float" /> <param index="0" name="from" type="float" /> <param index="1" name="to" type="float" /> @@ -888,6 +877,7 @@ [/codeblocks] [b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print] or [method print_rich]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. [b]Note:[/b] On Windows, only Windows 10 and later correctly displays ANSI escape codes in standard output. + [b]Note:[/b] Output displayed in the editor supports clickable [code skip-lint][url=address]text[/url][/code] tags. The [code skip-lint][url][/code] tag's [code]address[/code] value is handled by [method OS.shell_open] when clicked. </description> </method> <method name="print_verbose" qualifiers="vararg"> @@ -1009,7 +999,7 @@ <method name="randf"> <return type="float" /> <description> - Returns a random floating point value between [code]0.0[/code] and [code]1.0[/code] (inclusive). + Returns a random floating-point value between [code]0.0[/code] and [code]1.0[/code] (inclusive). [codeblocks] [gdscript] randf() # Returns e.g. 0.375671 @@ -1025,7 +1015,7 @@ <param index="0" name="from" type="float" /> <param index="1" name="to" type="float" /> <description> - Returns a random floating point value between [param from] and [param to] (inclusive). + Returns a random floating-point value between [param from] and [param to] (inclusive). [codeblocks] [gdscript] randf_range(0, 20.5) # Returns e.g. 7.45315 @@ -1043,7 +1033,8 @@ <param index="0" name="mean" type="float" /> <param index="1" name="deviation" type="float" /> <description> - Returns a normally-distributed pseudo-random floating point value using Box-Muller transform with the specified [param mean] and a standard [param deviation]. This is also called Gaussian distribution. + Returns a [url=https://en.wikipedia.org/wiki/Normal_distribution]normally-distributed[/url], pseudo-random floating-point value from the specified [param mean] and a standard [param deviation]. This is also known as a Gaussian distribution. + [b]Note:[/b] This method uses the [url=https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform]Box-Muller transform[/url] algorithm. </description> </method> <method name="randi"> @@ -1090,7 +1081,7 @@ [b]Note:[/b] This function is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use [method seed] to initialize the random number generator. </description> </method> - <method name="remap"> + <method name="remap" keywords="range, lerp, interpolate"> <return type="float" /> <param index="0" name="value" type="float" /> <param index="1" name="istart" type="float" /> @@ -1108,14 +1099,14 @@ <method name="rid_allocate_id"> <return type="int" /> <description> - Allocates a unique ID which can be used by the implementation to construct a RID. This is used mainly from native extensions to implement servers. + 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. </description> </method> <method name="rid_from_int64"> <return type="RID" /> <param index="0" name="base" type="int" /> <description> - Creates a RID from a [param base]. This is used mainly from native extensions to build servers. + Creates an RID from a [param base]. This is used mainly from native extensions to build servers. </description> </method> <method name="rotate_toward"> @@ -1271,7 +1262,7 @@ <param index="0" name="x" type="Variant" /> <param index="1" name="step" type="Variant" /> <description> - Returns the multiple of [param step] that is the closest to [param x]. This can also be used to round a floating point number to an arbitrary number of decimals. + Returns the multiple of [param step] that is the closest to [param 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] as [param step]. Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. [codeblock] snapped(100, 32) # Returns 96 @@ -1288,7 +1279,7 @@ <param index="0" name="x" type="float" /> <param index="1" name="step" type="float" /> <description> - Returns the multiple of [param step] that is the closest to [param x]. This can also be used to round a floating point number to an arbitrary number of decimals. + Returns the multiple of [param step] that is the closest to [param x]. This can also be used to round a floating-point number to an arbitrary number of decimals. A type-safe version of [method snapped], returning a [float]. [codeblock] snappedf(32.0, 2.5) # Returns 32.5 @@ -1393,7 +1384,7 @@ <description> Converts the given [param variant] to the given [param type], using the [enum Variant.Type] values. This method is generous with how it handles types, it can automatically convert between array types, convert numeric [String]s to [int], and converting most things to [String]. If the type conversion cannot be done, this method will return the default value for that type, for example converting [Rect2] to [Vector2] will always return [constant Vector2.ZERO]. This method will never show error messages as long as [param type] is a valid Variant type. - The returned value is a [Variant], but the data inside and the [enum Variant.Type] will be the same as the requested type. + The returned value is a [Variant], but the data inside and its type will be the same as the requested type. [codeblock] type_convert("Hi!", TYPE_INT) # Returns 0 type_convert("123", TYPE_INT) # Returns 123 @@ -1439,6 +1430,7 @@ <description> Encodes a [Variant] value to a byte array, without encoding objects. Deserialization can be done with [method bytes_to_var]. [b]Note:[/b] If you need object serialization, see [method var_to_bytes_with_objects]. + [b]Note:[/b] Encoding [Callable] is not supported and will result in an empty value, regardless of the data. </description> </method> <method name="var_to_bytes_with_objects"> @@ -1446,6 +1438,7 @@ <param index="0" name="variable" type="Variant" /> <description> Encodes a [Variant] value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with [method bytes_to_var_with_objects]. + [b]Note:[/b] Encoding [Callable] is not supported and will result in an empty value, regardless of the data. </description> </method> <method name="var_to_str"> @@ -1597,6 +1590,10 @@ <member name="Marshalls" type="Marshalls" setter="" getter=""> The [Marshalls] singleton. </member> + <member name="NativeMenu" type="NativeMenu" setter="" getter=""> + The [NativeMenu] singleton. + [b]Note:[/b] Only implemented on macOS. + </member> <member name="NavigationMeshGenerator" type="NavigationMeshGenerator" setter="" getter=""> The [NavigationMeshGenerator] singleton. </member> @@ -2382,6 +2379,16 @@ <constant name="KEY_MASK_GROUP_SWITCH" value="1073741824" enum="KeyModifierMask" is_bitfield="true"> Group Switch key mask. </constant> + <constant name="KEY_LOCATION_UNSPECIFIED" value="0" enum="KeyLocation"> + Used for keys which only appear once, or when a comparison doesn't need to differentiate the [code]LEFT[/code] and [code]RIGHT[/code] versions. + For example, when using [method InputEvent.is_match], an event which has [constant KEY_LOCATION_UNSPECIFIED] will match any [enum KeyLocation] on the passed event. + </constant> + <constant name="KEY_LOCATION_LEFT" value="1" enum="KeyLocation"> + A key which is to the left of its twin. + </constant> + <constant name="KEY_LOCATION_RIGHT" value="2" enum="KeyLocation"> + A key which is to the right of its twin. + </constant> <constant name="MOUSE_BUTTON_NONE" value="0" enum="MouseButton"> Enum value which doesn't correspond to any mouse button. This is used to initialize [enum MouseButton] properties with a generic state. </constant> @@ -2530,61 +2537,66 @@ The maximum number of game controller axes: OpenVR supports up to 5 Joysticks making a total of 10 axes. </constant> <constant name="MIDI_MESSAGE_NONE" value="0" enum="MIDIMessage"> - Enum value which doesn't correspond to any MIDI message. This is used to initialize [enum MIDIMessage] properties with a generic state. + Does not correspond to any MIDI message. This is the default value of [member InputEventMIDI.message]. </constant> <constant name="MIDI_MESSAGE_NOTE_OFF" value="8" enum="MIDIMessage"> - MIDI note OFF message. Not all MIDI devices send this event; some send [constant MIDI_MESSAGE_NOTE_ON] with zero velocity instead. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs. + MIDI message sent when a note is released. + [b]Note:[/b] Not all MIDI devices send this message; some may send [constant MIDI_MESSAGE_NOTE_ON] with [member InputEventMIDI.velocity] set to [code]0[/code]. </constant> <constant name="MIDI_MESSAGE_NOTE_ON" value="9" enum="MIDIMessage"> - MIDI note ON message. Some MIDI devices send this event with velocity zero instead of [constant MIDI_MESSAGE_NOTE_OFF], but implementations vary. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs. + MIDI message sent when a note is pressed. </constant> <constant name="MIDI_MESSAGE_AFTERTOUCH" value="10" enum="MIDIMessage"> - MIDI aftertouch message. This message is most often sent by pressing down on the key after it "bottoms out". + MIDI message sent to indicate a change in pressure while a note is being pressed down, also called aftertouch. </constant> <constant name="MIDI_MESSAGE_CONTROL_CHANGE" value="11" enum="MIDIMessage"> - MIDI control change message. This message is sent when a controller value changes. Controllers include devices such as pedals and levers. + 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 [url=https://en.wikipedia.org/wiki/General_MIDI#Controller_events]General MIDI specification[/url] for a small list. </constant> <constant name="MIDI_MESSAGE_PROGRAM_CHANGE" value="12" enum="MIDIMessage"> - MIDI program change message. This message sent when the program patch number changes. + MIDI message sent when the MIDI device changes its current instrument (also called [i]program[/i] or [i]preset[/i]). </constant> <constant name="MIDI_MESSAGE_CHANNEL_PRESSURE" value="13" enum="MIDIMessage"> - MIDI channel pressure message. This message is most often sent by pressing down on the key after it "bottoms out". This message is different from polyphonic after-touch as it indicates the highest pressure across all keys. + MIDI message sent to indicate a change in pressure for the whole channel. Some MIDI devices may send this instead of [constant MIDI_MESSAGE_AFTERTOUCH]. </constant> <constant name="MIDI_MESSAGE_PITCH_BEND" value="14" enum="MIDIMessage"> - MIDI pitch bend message. This message is sent to indicate a change in the pitch bender (wheel or lever, typically). + MIDI message sent when the value of the pitch bender changes, usually a wheel on the MIDI device. </constant> <constant name="MIDI_MESSAGE_SYSTEM_EXCLUSIVE" value="240" enum="MIDIMessage"> - MIDI system exclusive message. This has behavior exclusive to the device you're receiving input from. Getting this data is not implemented in Godot. + MIDI system exclusive (SysEx) message. This type of message is not standardized and it's highly dependent on the MIDI device sending it. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. </constant> <constant name="MIDI_MESSAGE_QUARTER_FRAME" value="241" enum="MIDIMessage"> - MIDI quarter frame message. Contains timing information that is used to synchronize MIDI devices. Getting this data is not implemented in Godot. + MIDI message sent every quarter frame to keep connected MIDI devices synchronized. Related to [constant MIDI_MESSAGE_TIMING_CLOCK]. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. </constant> <constant name="MIDI_MESSAGE_SONG_POSITION_POINTER" value="242" enum="MIDIMessage"> - MIDI song position pointer message. Gives the number of 16th notes since the start of the song. Getting this data is not implemented in Godot. + MIDI message sent to jump onto a new position in the current sequence or song. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. </constant> <constant name="MIDI_MESSAGE_SONG_SELECT" value="243" enum="MIDIMessage"> - MIDI song select message. Specifies which sequence or song is to be played. Getting this data is not implemented in Godot. + MIDI message sent to select a sequence or song to play. + [b]Note:[/b] Getting this message's data from [InputEventMIDI] is not implemented. </constant> <constant name="MIDI_MESSAGE_TUNE_REQUEST" value="246" enum="MIDIMessage"> - MIDI tune request message. Upon receiving a tune request, all analog synthesizers should tune their oscillators. + MIDI message sent to request a tuning calibration. Used on analog synthesizers. Most modern MIDI devices do not need this message. </constant> <constant name="MIDI_MESSAGE_TIMING_CLOCK" value="248" enum="MIDIMessage"> - MIDI timing clock message. Sent 24 times per quarter note when synchronization is required. + MIDI message sent 24 times after [constant MIDI_MESSAGE_QUARTER_FRAME], to keep connected MIDI devices synchronized. </constant> <constant name="MIDI_MESSAGE_START" value="250" enum="MIDIMessage"> - MIDI start message. Start the current sequence playing. This message will be followed with Timing Clocks. + MIDI message sent to start the current sequence or song from the beginning. </constant> <constant name="MIDI_MESSAGE_CONTINUE" value="251" enum="MIDIMessage"> - MIDI continue message. Continue at the point the sequence was stopped. + MIDI message sent to resume from the point the current sequence or song was paused. </constant> <constant name="MIDI_MESSAGE_STOP" value="252" enum="MIDIMessage"> - MIDI stop message. Stop the current sequence. + MIDI message sent to pause the current sequence or song. </constant> <constant name="MIDI_MESSAGE_ACTIVE_SENSING" value="254" enum="MIDIMessage"> - MIDI active sensing message. This message is intended to be sent repeatedly to tell the receiver that a connection is alive. + 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. </constant> <constant name="MIDI_MESSAGE_SYSTEM_RESET" value="255" enum="MIDIMessage"> - MIDI system reset message. Reset all receivers in the system to power-up status. It should not be sent on power-up itself. + 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. </constant> <constant name="OK" value="0" enum="Error"> Methods that return [enum Error] return [constant OK] when no error occurred. @@ -2823,6 +2835,7 @@ Hints that a [Color] property should be edited without affecting its transparency ([member Color.a] is not editable). </constant> <constant name="PROPERTY_HINT_OBJECT_ID" value="22" enum="PropertyHint"> + Hints that the property's value is an object encoded as object ID, with its type specified in the hint string. Used by the debugger. </constant> <constant name="PROPERTY_HINT_TYPE_STRING" value="23" enum="PropertyHint"> If a property is [String], hints that the property represents a particular type (class). This allows to select a type from the create dialog. The property will store the selected type as a string. @@ -2881,21 +2894,27 @@ [/codeblocks] [b]Note:[/b] The trailing colon is required for properly detecting built-in types. </constant> - <constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="24" enum="PropertyHint"> + <constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="24" enum="PropertyHint" deprecated="This hint is not used by the engine."> </constant> <constant name="PROPERTY_HINT_OBJECT_TOO_BIG" value="25" enum="PropertyHint"> + Hints that an object is too big to be sent via the debugger. </constant> <constant name="PROPERTY_HINT_NODE_PATH_VALID_TYPES" value="26" enum="PropertyHint"> + Hints that the hint string specifies valid node types for property of type [NodePath]. </constant> <constant name="PROPERTY_HINT_SAVE_FILE" value="27" enum="PropertyHint"> + Hints that a [String] property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the project's directory. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code]. See also [member FileDialog.filters]. </constant> <constant name="PROPERTY_HINT_GLOBAL_SAVE_FILE" value="28" enum="PropertyHint"> + Hints that a [String] property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the entire filesystem. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code]. See also [member FileDialog.filters]. </constant> - <constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="29" enum="PropertyHint"> + <constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="29" enum="PropertyHint" deprecated="This hint is not used by the engine."> </constant> <constant name="PROPERTY_HINT_INT_IS_POINTER" value="30" enum="PropertyHint"> + Hints that an [int] property is a pointer. Used by GDExtension. </constant> <constant name="PROPERTY_HINT_ARRAY_TYPE" value="31" enum="PropertyHint"> + Hints that a property is an [Array] with the stored type specified in the hint string. </constant> <constant name="PROPERTY_HINT_LOCALE_ID" value="32" enum="PropertyHint"> Hints that a string property is a locale code. Editing it will show a locale dialog for picking language and country. @@ -2904,6 +2923,7 @@ Hints that a dictionary property is string translation map. Dictionary keys are locale codes and, values are translated strings. </constant> <constant name="PROPERTY_HINT_NODE_TYPE" value="34" enum="PropertyHint"> + Hints that a property is an instance of a [Node]-derived type, optionally specified via the hint string (e.g. [code]"Node2D"[/code]). Editing it will show a dialog for picking a node from the scene. </constant> <constant name="PROPERTY_HINT_HIDE_QUATERNION_EDIT" value="35" enum="PropertyHint"> Hints that a quaternion property should disable the temporary euler editor. @@ -2942,6 +2962,7 @@ Used to group properties together in the editor in a subgroup (under a group). See [EditorInspector]. </constant> <constant name="PROPERTY_USAGE_CLASS_IS_BITFIELD" value="512" enum="PropertyUsageFlags" is_bitfield="true"> + The property is a bitfield, i.e. it contains multiple flags represented as bits. </constant> <constant name="PROPERTY_USAGE_NO_INSTANCE_STATE" value="1024" enum="PropertyUsageFlags" is_bitfield="true"> The property does not save its state in [PackedScene]. @@ -2953,14 +2974,18 @@ The property is a script variable which should be serialized and saved in the scene file. </constant> <constant name="PROPERTY_USAGE_STORE_IF_NULL" value="8192" enum="PropertyUsageFlags" is_bitfield="true"> + The property value of type [Object] will be stored even if its value is [code]null[/code]. </constant> <constant name="PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED" value="16384" enum="PropertyUsageFlags" is_bitfield="true"> + If this property is modified, all inspector fields will be refreshed. </constant> - <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags" is_bitfield="true"> + <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags" is_bitfield="true" deprecated="This flag is not used by the engine."> </constant> <constant name="PROPERTY_USAGE_CLASS_IS_ENUM" value="65536" enum="PropertyUsageFlags" is_bitfield="true"> + The property is an enum, i.e. it only takes named integer constants from its associated enumeration. </constant> <constant name="PROPERTY_USAGE_NIL_IS_VARIANT" value="131072" enum="PropertyUsageFlags" is_bitfield="true"> + If property has [code]nil[/code] as default value, its type will be [Variant]. </constant> <constant name="PROPERTY_USAGE_ARRAY" value="262144" enum="PropertyUsageFlags" is_bitfield="true"> The property is an array. @@ -2975,16 +3000,21 @@ The property is only shown in the editor if modern renderers are supported (the Compatibility rendering method is excluded). </constant> <constant name="PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT" value="4194304" enum="PropertyUsageFlags" is_bitfield="true"> + The [NodePath] property will always be relative to the scene's root. Mostly useful for local resources. </constant> <constant name="PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT" value="8388608" enum="PropertyUsageFlags" is_bitfield="true"> + Use when a resource is created on the fly, i.e. the getter will always return a different instance. [ResourceSaver] needs this information to properly save such resources. </constant> <constant name="PROPERTY_USAGE_KEYING_INCREMENTS" value="16777216" enum="PropertyUsageFlags" is_bitfield="true"> + Inserting an animation key frame of this property will automatically increment the value, allowing to easily keyframe multiple values in a row. </constant> - <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags" is_bitfield="true"> + <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags" is_bitfield="true" deprecated="This flag is not used by the engine."> </constant> <constant name="PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT" value="67108864" enum="PropertyUsageFlags" is_bitfield="true"> + When this property is a [Resource] and base object is a [Node], a resource instance will be automatically created whenever the node is created in the editor. </constant> <constant name="PROPERTY_USAGE_EDITOR_BASIC_SETTING" value="134217728" enum="PropertyUsageFlags" is_bitfield="true"> + The property is considered a basic setting and will appear even when advanced mode is disabled. Used for project settings. </constant> <constant name="PROPERTY_USAGE_READ_ONLY" value="268435456" enum="PropertyUsageFlags" is_bitfield="true"> The property is read-only in the [EditorInspector]. diff --git a/doc/classes/AABB.xml b/doc/classes/AABB.xml index c1c637d2d6..427d38d421 100644 --- a/doc/classes/AABB.xml +++ b/doc/classes/AABB.xml @@ -4,10 +4,10 @@ A 3D axis-aligned bounding box. </brief_description> <description> - [AABB] consists of a position, a size, and several utility functions. It is typically used for fast overlap tests. - It uses floating-point coordinates. The 2D counterpart to [AABB] is [Rect2]. - Negative values for [member size] are not supported and will not work for most methods. Use [method abs] to get an AABB with a positive size. - [b]Note:[/b] Unlike [Rect2], [AABB] does not have a variant that uses integer coordinates. + The [AABB] built-in [Variant] type represents an axis-aligned bounding box in a 3D space. It is defined by its [member position] and [member size], which are [Vector3]. It is frequently used for fast overlap tests (see [method intersects]). Although [AABB] itself is axis-aligned, it can be combined with [Transform3D] to represent a rotated or skewed bounding box. + It uses floating-point coordinates. The 2D counterpart to [AABB] is [Rect2]. There is no version of [AABB] that uses integer coordinates. + [b]Note:[/b] Negative values for [member size] are not supported. With negative size, most [AABB] methods do not work correctly. Use [method abs] to get an equivalent [AABB] with a non-negative size. + [b]Note:[/b] In a boolean context, a [AABB] evaluates to [code]false[/code] if both [member position] and [member size] are zero (equal to [constant Vector3.ZERO]). Otherwise, it always evaluates to [code]true[/code]. </description> <tutorials> <link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link> @@ -18,7 +18,7 @@ <constructor name="AABB"> <return type="AABB" /> <description> - Constructs a default-initialized [AABB] with default (zero) values of [member position] and [member size]. + Constructs an [AABB] with its [member position] and [member size] set to [constant Vector3.ZERO]. </description> </constructor> <constructor name="AABB"> @@ -33,7 +33,7 @@ <param index="0" name="position" type="Vector3" /> <param index="1" name="size" type="Vector3" /> <description> - Constructs an [AABB] from a position and size. + Constructs an [AABB] by [param position] and [param size]. </description> </constructor> </constructors> @@ -41,34 +41,78 @@ <method name="abs" qualifiers="const"> <return type="AABB" /> <description> - Returns an AABB with equivalent position and size, modified so that the most-negative corner is the origin and the size is positive. + Returns an [AABB] equivalent to this bounding box, with its width, height, and depth modified to be non-negative values. + [codeblocks] + [gdscript] + var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5)) + var absolute = box.abs() + print(absolute.position) # Prints (-15, -10, 0) + print(absolute.size) # Prints (20, 10, 5) + [/gdscript] + [csharp] + var box = new Aabb(new Vector3(5, 0, 5), new Vector3(-20, -10, -5)); + var absolute = box.Abs(); + GD.Print(absolute.Position); // Prints (-15, -10, 0) + GD.Print(absolute.Size); // Prints (20, 10, 5) + [/csharp] + [/codeblocks] + [b]Note:[/b] It's recommended to use this method when [member size] is negative, as most other methods in Godot assume that the [member size]'s components are greater than [code]0[/code]. </description> </method> <method name="encloses" qualifiers="const"> <return type="bool" /> <param index="0" name="with" type="AABB" /> <description> - Returns [code]true[/code] if this [AABB] completely encloses another one. + Returns [code]true[/code] if this bounding box [i]completely[/i] encloses the [param with] box. The edges of both boxes are included. + [codeblocks] + [gdscript] + var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4)) + var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3)) + var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8)) + + print(a.encloses(a)) # Prints true + print(a.encloses(b)) # Prints true + print(a.encloses(c)) # Prints false + [/gdscript] + [csharp] + var a = new Aabb(new Vector3(0, 0, 0), new Vector3(4, 4, 4)); + var b = new Aabb(new Vector3(1, 1, 1), new Vector3(3, 3, 3)); + var c = new Aabb(new Vector3(2, 2, 2), new Vector3(8, 8, 8)); + + GD.Print(a.Encloses(a)); // Prints True + GD.Print(a.Encloses(b)); // Prints True + GD.Print(a.Encloses(c)); // Prints False + [/csharp] + [/codeblocks] </description> </method> <method name="expand" qualifiers="const"> <return type="AABB" /> <param index="0" name="to_point" type="Vector3" /> <description> - Returns a copy of this [AABB] expanded to include a given point. - [b]Example:[/b] + Returns a copy of this bounding box expanded to align the edges with the given [param to_point], if necessary. [codeblocks] [gdscript] - # position (-3, 2, 0), size (1, 1, 1) - var box = AABB(Vector3(-3, 2, 0), Vector3(1, 1, 1)) - # position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2) - var box2 = box.expand(Vector3(0, -1, 2)) + var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5)) + + box = box.expand(Vector3(10, 0, 0)) + print(box.position) # Prints (0, 0, 0) + print(box.size) # Prints (10, 2, 5) + + box = box.expand(Vector3(-5, 0, 5)) + print(box.position) # Prints (-5, 0, 0) + print(box.size) # Prints (15, 2, 5) [/gdscript] [csharp] - // position (-3, 2, 0), size (1, 1, 1) - var box = new Aabb(new Vector3(-3, 2, 0), new Vector3(1, 1, 1)); - // position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2) - var box2 = box.Expand(new Vector3(0, -1, 2)); + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5)); + + box = box.Expand(new Vector3(10, 0, 0)); + GD.Print(box.Position); // Prints (0, 0, 0) + GD.Print(box.Size); // Prints (10, 2, 5) + + box = box.Expand(new Vector3(-5, 0, 5)); + GD.Print(box.Position); // Prints (-5, 0, 0) + GD.Print(box.Size); // Prints (15, 2, 5) [/csharp] [/codeblocks] </description> @@ -76,111 +120,188 @@ <method name="get_center" qualifiers="const"> <return type="Vector3" /> <description> - Returns the center of the [AABB], which is equal to [member position] + ([member size] / 2). + Returns the center point of the bounding box. This is the same as [code]position + (size / 2.0)[/code]. </description> </method> <method name="get_endpoint" qualifiers="const"> <return type="Vector3" /> <param index="0" name="idx" type="int" /> <description> - Gets the position of the 8 endpoints of the [AABB] in space. + Returns the position of one of the 8 vertices that compose this bounding box. With a [param idx] of [code]0[/code] this is the same as [member position], and a [param idx] of [code]7[/code] is the same as [member end]. </description> </method> <method name="get_longest_axis" qualifiers="const"> <return type="Vector3" /> <description> - Returns the normalized longest axis of the [AABB]. + Returns the longest normalized axis of this bounding box's [member size], as a [Vector3] ([constant Vector3.RIGHT], [constant Vector3.UP], or [constant Vector3.BACK]). + [codeblocks] + [gdscript] + var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8)) + + print(box.get_longest_axis()) # Prints (0, 0, 1) + print(box.get_longest_axis_index()) # Prints 2 + print(box.get_longest_axis_size()) # Prints 8 + [/gdscript] + [csharp] + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8)); + + GD.Print(box.GetLongestAxis()); // Prints (0, 0, 1) + GD.Print(box.GetLongestAxisIndex()); // Prints 2 + GD.Print(box.GetLongestAxisSize()); // Prints 8 + [/csharp] + [/codeblocks] + See also [method get_longest_axis_index] and [method get_longest_axis_size]. </description> </method> <method name="get_longest_axis_index" qualifiers="const"> <return type="int" /> <description> - Returns the index of the longest axis of the [AABB] (according to [Vector3]'s [code]AXIS_*[/code] constants). + Returns the index to the longest axis of this bounding box's [member size] (see [constant Vector3.AXIS_X], [constant Vector3.AXIS_Y], and [constant Vector3.AXIS_Z]). + For an example, see [method get_longest_axis]. </description> </method> <method name="get_longest_axis_size" qualifiers="const"> <return type="float" /> <description> - Returns the scalar length of the longest axis of the [AABB]. + Returns the longest dimension of this bounding box's [member size]. + For an example, see [method get_longest_axis]. </description> </method> <method name="get_shortest_axis" qualifiers="const"> <return type="Vector3" /> <description> - Returns the normalized shortest axis of the [AABB]. + Returns the shortest normaalized axis of this bounding box's [member size], as a [Vector3] ([constant Vector3.RIGHT], [constant Vector3.UP], or [constant Vector3.BACK]). + [codeblocks] + [gdscript] + var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8)) + + print(box.get_shortest_axis()) # Prints (1, 0, 0) + print(box.get_shortest_axis_index()) # Prints 0 + print(box.get_shortest_axis_size()) # Prints 2 + [/gdscript] + [csharp] + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8)); + + GD.Print(box.GetShortestAxis()); // Prints (1, 0, 0) + GD.Print(box.GetShortestAxisIndex()); // Prints 0 + GD.Print(box.GetShortestAxisSize()); // Prints 2 + [/csharp] + [/codeblocks] + See also [method get_shortest_axis_index] and [method get_shortest_axis_size]. </description> </method> <method name="get_shortest_axis_index" qualifiers="const"> <return type="int" /> <description> - Returns the index of the shortest axis of the [AABB] (according to [Vector3]::AXIS* enum). + Returns the index to the shortest axis of this bounding box's [member size] (see [constant Vector3.AXIS_X], [constant Vector3.AXIS_Y], and [constant Vector3.AXIS_Z]). + For an example, see [method get_shortest_axis]. </description> </method> <method name="get_shortest_axis_size" qualifiers="const"> <return type="float" /> <description> - Returns the scalar length of the shortest axis of the [AABB]. + Returns the shortest dimension of this bounding box's [member size]. + For an example, see [method get_shortest_axis]. </description> </method> <method name="get_support" qualifiers="const"> <return type="Vector3" /> <param index="0" name="dir" type="Vector3" /> <description> - Returns the vertex of the AABB that's the farthest in a given direction. This point is commonly known as the support point in collision detection algorithms. + Returns the vertex's position of this bounding box that's the farthest in the given direction. This point is commonly known as the support point in collision detection algorithms. </description> </method> <method name="get_volume" qualifiers="const"> <return type="float" /> <description> - Returns the volume of the [AABB]. + Returns the bounding box's volume. This is equivalent to [code]size.x * size.y * size.z[/code]. See also [method has_volume]. </description> </method> <method name="grow" qualifiers="const"> <return type="AABB" /> <param index="0" name="by" type="float" /> <description> - Returns a copy of the [AABB] grown a given number of units towards all the sides. + Returns a copy of this bounding box extended on all sides by the given amount [param by]. A negative amount shrinks the box instead. + [codeblocks] + [gdscript] + var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4) + print(a.position) # Prints (0, 0, 0) + print(a.size) # Prints (16, 16, 16) + + var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2) + print(b.position) # Prints (-2, -2, -2) + print(b.size) # Prints (12, 8, 6) + [/gdscript] + [csharp] + var a = new Aabb(new Vector3(4, 4, 4), new Vector3(8, 8, 8)).Grow(4); + GD.Print(a.Position); // Prints (0, 0, 0) + GD.Print(a.Size); // Prints (16, 16, 16) + + var b = new Aabb(new Vector3(0, 0, 0), new Vector3(8, 4, 2)).Grow(2); + GD.Print(b.Position); // Prints (-2, -2, -2) + GD.Print(b.Size); // Prints (12, 8, 6) + [/csharp] + [/codeblocks] </description> </method> <method name="has_point" qualifiers="const"> <return type="bool" /> <param index="0" name="point" type="Vector3" /> <description> - Returns [code]true[/code] if the [AABB] contains a point. Points on the faces of the AABB are considered included, though float-point precision errors may impact the accuracy of such checks. - [b]Note:[/b] This method is not reliable for [AABB] with a [i]negative size[/i]. Use [method abs] to get a positive sized equivalent [AABB] to check for contained points. + Returns [code]true[/code] if the bounding box contains the given [param point]. By convention, points exactly on the right, top, and front sides are [b]not[/b] included. + [b]Note:[/b] This method is not reliable for [AABB] with a [i]negative[/i] [member size]. Use [method abs] first to get a valid bounding box. </description> </method> <method name="has_surface" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the [AABB] has a surface or a length, and [code]false[/code] if the [AABB] is empty (all components of [member size] are zero or negative). + Returns [code]true[/code] if this bounding box has a surface or a length, that is, at least one component of [member size] is greater than [code]0[/code]. Otherwise, returns [code]false[/code]. </description> </method> <method name="has_volume" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the [AABB] has a volume, and [code]false[/code] if the [AABB] is flat, empty, or has a negative [member size]. + Returns [code]true[/code] if this bounding box's width, height, and depth are all positive. See also [method get_volume]. </description> </method> <method name="intersection" qualifiers="const"> <return type="AABB" /> <param index="0" name="with" type="AABB" /> <description> - Returns the intersection between two [AABB]. An empty AABB (size [code](0, 0, 0)[/code]) is returned on failure. + Returns the intersection between this bounding box and [param with]. If the boxes do not intersect, returns an empty [AABB]. If the boxes intersect at the edge, returns a flat [AABB] with no volume (see [method has_surface] and [method has_volume]). + [codeblocks] + [gdscript] + var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8)) + var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4)) + + var intersection = box1.intersection(box2) + print(intersection.position) # Prints (2, 0, 2) + print(intersection.size) # Prints (3, 2, 4) + [/gdscript] + [csharp] + var box1 = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 8)); + var box2 = new Aabb(new Vector3(2, 0, 2), new Vector3(8, 4, 4)); + + var intersection = box1.Intersection(box2); + GD.Print(intersection.Position); // Prints (2, 0, 2) + GD.Print(intersection.Size); // Prints (3, 2, 4) + [/csharp] + [/codeblocks] + [b]Note:[/b] If you only need to know whether two bounding boxes are intersecting, use [method intersects], instead. </description> </method> <method name="intersects" qualifiers="const"> <return type="bool" /> <param index="0" name="with" type="AABB" /> <description> - Returns [code]true[/code] if the [AABB] overlaps with another. + Returns [code]true[/code] if this bounding box overlaps with the box [param with]. The edges of both boxes are [i]always[/i] excluded. </description> </method> <method name="intersects_plane" qualifiers="const"> <return type="bool" /> <param index="0" name="plane" type="Plane" /> <description> - Returns [code]true[/code] if the [AABB] is on both sides of a plane. + Returns [code]true[/code] if this bounding box is on both sides of the given [param plane]. </description> </method> <method name="intersects_ray" qualifiers="const"> @@ -188,7 +309,8 @@ <param index="0" name="from" type="Vector3" /> <param index="1" name="dir" type="Vector3" /> <description> - Returns the point of intersection of the given ray with this [AABB] or [code]null[/code] if there is no intersection. Ray length is infinite. + Returns the first point where this bounding box and the given ray intersect, as a [Vector3]. If no intersection occurs, returns [code]null[/code]. + The ray begin at [param from], faces [param dir] and extends towards infinity. </description> </method> <method name="intersects_segment" qualifiers="const"> @@ -196,40 +318,41 @@ <param index="0" name="from" type="Vector3" /> <param index="1" name="to" type="Vector3" /> <description> - Returns the point of intersection between [param from] and [param to] with this [AABB] or [code]null[/code] if there is no intersection. + Returns the first point where this bounding box and the given segment intersect, as a [Vector3]. If no intersection occurs, returns [code]null[/code]. + The segment begins at [param from] and ends at [param to]. </description> </method> <method name="is_equal_approx" qualifiers="const"> <return type="bool" /> <param index="0" name="aabb" type="AABB" /> <description> - Returns [code]true[/code] if this [AABB] and [param aabb] are approximately equal, by calling [method @GlobalScope.is_equal_approx] on each component. + Returns [code]true[/code] if this bounding box and [param aabb] are approximately equal, by calling [method Vector2.is_equal_approx] on the [member position] and the [member size]. </description> </method> <method name="is_finite" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this [AABB] is finite, by calling [method @GlobalScope.is_finite] on each component. + Returns [code]true[/code] if this bounding box's values are finite, by calling [method Vector2.is_finite] on the [member position] and the [member size]. </description> </method> <method name="merge" qualifiers="const"> <return type="AABB" /> <param index="0" name="with" type="AABB" /> <description> - Returns a larger [AABB] that contains both this [AABB] and [param with]. + Returns an [AABB] that encloses both this bounding box and [param with] around the edges. See also [method encloses]. </description> </method> </methods> <members> <member name="end" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)"> - Ending corner. This is calculated as [code]position + size[/code]. Setting this value will change the size. + The ending point. This is usually the corner on the top-right and forward of the bounding box, and is equivalent to [code]position + size[/code]. Setting this point affects the [member size]. </member> <member name="position" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)"> - Beginning corner. Typically has values lower than [member end]. + The origin point. This is usually the corner on the bottom-left and back of the bounding box. </member> <member name="size" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)"> - Size from [member position] to [member end]. Typically, all components are positive. - If the size is negative, you can use [method abs] to fix it. + The bounding box's width, height, and depth starting from [member position]. Setting this value also affects the [member end] point. + [b]Note:[/b] It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the [member position] is the bottom-left-back corner, and the [member end] is the top-right-forward corner. To get an equivalent bounding box with non-negative size, use [method abs]. </member> </members> <operators> @@ -237,7 +360,7 @@ <return type="bool" /> <param index="0" name="right" type="AABB" /> <description> - Returns [code]true[/code] if the AABBs are not equal. + Returns [code]true[/code] if the [member position] or [member size] of both bounding boxes are not equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -254,7 +377,7 @@ <return type="bool" /> <param index="0" name="right" type="AABB" /> <description> - Returns [code]true[/code] if the AABBs are exactly equal. + Returns [code]true[/code] if both [member position] and [member size] of the bounding boxes are exactly equal, respectively. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> diff --git a/doc/classes/AStar2D.xml b/doc/classes/AStar2D.xml index f10e80e048..2ea6aa15bd 100644 --- a/doc/classes/AStar2D.xml +++ b/doc/classes/AStar2D.xml @@ -139,8 +139,10 @@ <return type="PackedInt64Array" /> <param index="0" name="from_id" type="int" /> <param index="1" name="to_id" type="int" /> + <param index="2" name="allow_partial_path" type="bool" default="false" /> <description> Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. + If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached. [codeblocks] [gdscript] var astar = AStar2D.new() @@ -228,9 +230,11 @@ <return type="PackedVector2Array" /> <param index="0" name="from_id" type="int" /> <param index="1" name="to_id" type="int" /> + <param index="2" name="allow_partial_path" type="bool" default="false" /> <description> Returns an array with the points that are in the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. - [b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty [PackedVector2Array] and will print an error message. + If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached. + [b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty array and will print an error message. </description> </method> <method name="get_point_position" qualifiers="const"> diff --git a/doc/classes/AStar3D.xml b/doc/classes/AStar3D.xml index e2afeef377..281f4edcc1 100644 --- a/doc/classes/AStar3D.xml +++ b/doc/classes/AStar3D.xml @@ -168,8 +168,10 @@ <return type="PackedInt64Array" /> <param index="0" name="from_id" type="int" /> <param index="1" name="to_id" type="int" /> + <param index="2" name="allow_partial_path" type="bool" default="false" /> <description> Returns an array with the IDs of the points that form the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path. + If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached. [codeblocks] [gdscript] var astar = AStar3D.new() @@ -255,9 +257,11 @@ <return type="PackedVector3Array" /> <param index="0" name="from_id" type="int" /> <param index="1" name="to_id" type="int" /> + <param index="2" name="allow_partial_path" type="bool" default="false" /> <description> Returns an array with the points that are in the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path. - [b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty [PackedVector3Array] and will print an error message. + If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached. + [b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty array and will print an error message. </description> </method> <method name="get_point_position" qualifiers="const"> diff --git a/doc/classes/AStarGrid2D.xml b/doc/classes/AStarGrid2D.xml index 277630588a..5ccc0c8f2a 100644 --- a/doc/classes/AStarGrid2D.xml +++ b/doc/classes/AStarGrid2D.xml @@ -75,17 +75,21 @@ <return type="Vector2i[]" /> <param index="0" name="from_id" type="Vector2i" /> <param index="1" name="to_id" type="Vector2i" /> + <param index="2" name="allow_partial_path" type="bool" default="false" /> <description> Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. + If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached. </description> </method> <method name="get_point_path"> <return type="PackedVector2Array" /> <param index="0" name="from_id" type="Vector2i" /> <param index="1" name="to_id" type="Vector2i" /> + <param index="2" name="allow_partial_path" type="bool" default="false" /> <description> Returns an array with the points that are in the path found by [AStarGrid2D] between the given points. The array is ordered from the starting point to the ending point of the path. - [b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty [PackedVector3Array] and will print an error message. + If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached. + [b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty array and will print an error message. </description> </method> <method name="get_point_position" qualifiers="const"> @@ -157,6 +161,9 @@ </method> </methods> <members> + <member name="cell_shape" type="int" setter="set_cell_shape" getter="get_cell_shape" enum="AStarGrid2D.CellShape" default="0"> + The cell shape. Affects how the positions are placed in the grid. If changed, [method update] needs to be called before finding the next path. + </member> <member name="cell_size" type="Vector2" setter="set_cell_size" getter="get_cell_size" default="Vector2(1, 1)"> The size of the point cell which will be applied to calculate the resulting point position returned by [method get_point_path]. If changed, [method update] needs to be called before finding the next path. </member> @@ -179,9 +186,8 @@ <member name="region" type="Rect2i" setter="set_region" getter="get_region" default="Rect2i(0, 0, 0, 0)"> The region of grid cells available for pathfinding. If changed, [method update] needs to be called before finding the next path. </member> - <member name="size" type="Vector2i" setter="set_size" getter="get_size" default="Vector2i(0, 0)" is_deprecated="true"> + <member name="size" type="Vector2i" setter="set_size" getter="get_size" default="Vector2i(0, 0)" deprecated="Use [member region] instead."> The size of the grid (number of cells of size [member cell_size] on each axis). If changed, [method update] needs to be called before finding the next path. - [i]Deprecated.[/i] Use [member region] instead. </member> </members> <constants> @@ -238,5 +244,17 @@ <constant name="DIAGONAL_MODE_MAX" value="4" enum="DiagonalMode"> Represents the size of the [enum DiagonalMode] enum. </constant> + <constant name="CELL_SHAPE_SQUARE" value="0" enum="CellShape"> + Rectangular cell shape. + </constant> + <constant name="CELL_SHAPE_ISOMETRIC_RIGHT" value="1" enum="CellShape"> + Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes up-right, and the vertical one goes down-right. + </constant> + <constant name="CELL_SHAPE_ISOMETRIC_DOWN" value="2" enum="CellShape"> + Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes down-right, and the vertical one goes down-left. + </constant> + <constant name="CELL_SHAPE_MAX" value="3" enum="CellShape"> + Represents the size of the [enum CellShape] enum. + </constant> </constants> </class> diff --git a/doc/classes/AcceptDialog.xml b/doc/classes/AcceptDialog.xml index 59cbb38036..7fbdd4272d 100644 --- a/doc/classes/AcceptDialog.xml +++ b/doc/classes/AcceptDialog.xml @@ -44,14 +44,14 @@ </method> <method name="register_text_enter"> <return type="void" /> - <param index="0" name="line_edit" type="Control" /> + <param index="0" name="line_edit" type="LineEdit" /> <description> Registers a [LineEdit] in the dialog. When the enter key is pressed, the dialog will be accepted. </description> </method> <method name="remove_button"> <return type="void" /> - <param index="0" name="button" type="Control" /> + <param index="0" name="button" type="Button" /> <description> Removes the [param button] from the dialog. Does NOT free the [param button]. The [param button] must be a [Button] added with [method add_button] or [method add_cancel_button] method. After removal, pressing the [param button] will no longer emit this dialog's [signal custom_action] or [signal canceled] signals. </description> diff --git a/doc/classes/AnimatedSprite2D.xml b/doc/classes/AnimatedSprite2D.xml index d4f840cfa7..4b38773505 100644 --- a/doc/classes/AnimatedSprite2D.xml +++ b/doc/classes/AnimatedSprite2D.xml @@ -84,6 +84,7 @@ </member> <member name="centered" type="bool" setter="set_centered" getter="is_centered" default="true"> If [code]true[/code], texture will be centered. + [b]Note:[/b] For games with a pixel art aesthetic, textures may appear deformed when centered. This is caused by their position being between pixels. To prevent this, set this property to [code]false[/code], or consider enabling [member ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel] and [member ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel]. </member> <member name="flip_h" type="bool" setter="set_flip_h" getter="is_flipped_h" default="false"> If [code]true[/code], texture is flipped horizontally. @@ -117,6 +118,7 @@ <signal name="animation_finished"> <description> Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. + [b]Note:[/b] This signal is not emitted if an animation is looping. </description> </signal> <signal name="animation_looped"> diff --git a/doc/classes/AnimatedSprite3D.xml b/doc/classes/AnimatedSprite3D.xml index ff4bf97122..5f0a6c3e8d 100644 --- a/doc/classes/AnimatedSprite3D.xml +++ b/doc/classes/AnimatedSprite3D.xml @@ -104,6 +104,7 @@ <signal name="animation_finished"> <description> Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. + [b]Note:[/b] This signal is not emitted if an animation is looping. </description> </signal> <signal name="animation_looped"> diff --git a/doc/classes/AnimatedTexture.xml b/doc/classes/AnimatedTexture.xml index a5cacff987..d443541e26 100644 --- a/doc/classes/AnimatedTexture.xml +++ b/doc/classes/AnimatedTexture.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AnimatedTexture" inherits="Texture2D" is_deprecated="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AnimatedTexture" inherits="Texture2D" deprecated="This class does not work properly in current versions and may be removed in the future. There is currently no equivalent workaround." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Proxy texture for simple frame-based animations. </brief_description> @@ -9,7 +9,6 @@ [AnimatedTexture] currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one. [b]Note:[/b] AnimatedTexture doesn't support using [AtlasTexture]s. Each frame needs to be a separate [Texture2D]. [b]Warning:[/b] The current implementation is not efficient for the modern renderers. - [i]Deprecated.[/i] This class is deprecated, and might be removed in a future release. </description> <tutorials> </tutorials> diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index 15f6b16439..b00889f483 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -8,21 +8,23 @@ [codeblocks] [gdscript] # This creates an animation that makes the node "Enemy" move to the right by - # 100 pixels in 0.5 seconds. + # 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, 0.5, 100) + animation.track_insert_key(track_index, 2.0, 100) + animation.length = 2.0 [/gdscript] [csharp] // This creates an animation that makes the node "Enemy" move to the right by - // 100 pixels in 0.5 seconds. + // 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, 0.5f, 100); + animation.TrackInsertKey(trackIndex, 2.0f, 100); + animation.Length = 2.0f; [/csharp] [/codeblocks] Animations are just data containers, and must be added to nodes such as an [AnimationPlayer] to be played back. Animation tracks have different types, each with its own set of dedicated methods. Check [enum TrackType] to see available types. @@ -232,6 +234,7 @@ <return type="float" /> <param index="0" name="track_idx" type="int" /> <param index="1" name="time_sec" type="float" /> + <param index="2" name="backward" type="bool" default="false" /> <description> Returns the interpolated blend shape value at the given time (in seconds). The [param track_idx] must be the index of a blend shape track. </description> @@ -303,6 +306,7 @@ <return type="Vector3" /> <param index="0" name="track_idx" type="int" /> <param index="1" name="time_sec" type="float" /> + <param index="2" name="backward" type="bool" default="false" /> <description> Returns the interpolated position value at the given time (in seconds). The [param track_idx] must be the index of a 3D position track. </description> @@ -327,6 +331,7 @@ <return type="Quaternion" /> <param index="0" name="track_idx" type="int" /> <param index="1" name="time_sec" type="float" /> + <param index="2" name="backward" type="bool" default="false" /> <description> Returns the interpolated rotation value at the given time (in seconds). The [param track_idx] must be the index of a 3D rotation track. </description> @@ -344,6 +349,7 @@ <return type="Vector3" /> <param index="0" name="track_idx" type="int" /> <param index="1" name="time_sec" type="float" /> + <param index="2" name="backward" type="bool" default="false" /> <description> Returns the interpolated scale value at the given time (in seconds). The [param track_idx] must be the index of a 3D scale track. </description> @@ -353,8 +359,10 @@ <param index="0" name="track_idx" type="int" /> <param index="1" name="time" type="float" /> <param index="2" name="find_mode" type="int" enum="Animation.FindMode" default="0" /> + <param index="3" name="limit" type="bool" default="false" /> <description> Finds the key index by time in a given track. Optionally, only find it if the approx/exact time is given. + If [param limit] is [code]true[/code], it does not return keys outside the animation range. </description> </method> <method name="track_get_interpolation_loop_wrap" qualifiers="const"> @@ -572,6 +580,7 @@ <return type="Variant" /> <param index="0" name="track_idx" type="int" /> <param index="1" name="time_sec" type="float" /> + <param index="2" name="backward" type="bool" default="false" /> <description> Returns the interpolated value at the given time (in seconds). The [param track_idx] must be the index of a value track. </description> @@ -649,7 +658,7 @@ Update at the keyframes. </constant> <constant name="UPDATE_CAPTURE" value="2" enum="UpdateMode"> - Same as linear interpolation, but also interpolates from the current value (i.e. dynamically at runtime) if the first key isn't at 0 seconds. + Same as [constant UPDATE_CONTINUOUS] but works as a flag to capture the value of the current object and perform interpolation in some methods. See also [method AnimationMixer.capture] and [method AnimationPlayer.play_with_capture]. </constant> <constant name="LOOP_NONE" value="0" enum="LoopMode"> At both ends of the animation, the animation will stop playing. diff --git a/doc/classes/AnimationMixer.xml b/doc/classes/AnimationMixer.xml index 4a489a3ef2..a77e9e28c6 100644 --- a/doc/classes/AnimationMixer.xml +++ b/doc/classes/AnimationMixer.xml @@ -15,10 +15,10 @@ <param index="0" name="animation" type="Animation" /> <param index="1" name="track" type="int" /> <param index="2" name="value" type="Variant" /> - <param index="3" name="object" type="Object" /> - <param index="4" name="object_idx" type="int" /> + <param index="3" name="object_id" type="int" /> + <param index="4" name="object_sub_idx" type="int" /> <description> - A virtual function for processing after key getting during playback. + A virtual function for processing after getting a key during playback. </description> </method> <method name="add_animation_library"> @@ -36,6 +36,18 @@ Manually advance the animations by the specified time (in seconds). </description> </method> + <method name="capture"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="duration" type="float" /> + <param index="2" name="trans_type" type="int" enum="Tween.TransitionType" default="0" /> + <param index="3" name="ease_type" type="int" enum="Tween.EaseType" default="0" /> + <description> + If the animation track specified by [param name] has an option [constant Animation.UPDATE_CAPTURE], stores current values of the objects indicated by the track path as a cache. If there is already a captured cache, the old cache is discarded. + After this it will interpolate with current animation blending result during the playback process for the time specified by [param duration], working like a crossfade. + You can specify [param trans_type] as the curve for the interpolation. For better results, it may be appropriate to specify [constant Tween.TRANS_LINEAR] for cases where the first key of the track begins with a non-zero value or where the key value does not change, and [constant Tween.TRANS_QUAD] for cases where the key value changes linearly. + </description> + </method> <method name="clear_caches"> <return type="void" /> <description> @@ -68,7 +80,7 @@ <param index="0" name="name" type="StringName" /> <description> Returns the first [AnimationLibrary] with key [param name] or [code]null[/code] if not found. - To get the [AnimationPlayer]'s global animation library, use [code]get_animation_library("")[/code]. + To get the [AnimationMixer]'s global animation library, use [code]get_animation_library("")[/code]. </description> </method> <method name="get_animation_library_list" qualifiers="const"> @@ -227,14 +239,14 @@ <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if the [AnimationPlayer] stores an [Animation] with key [param name]. + Returns [code]true[/code] if the [AnimationMixer] stores an [Animation] with key [param name]. </description> </method> <method name="has_animation_library" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if the [AnimationPlayer] stores an [AnimationLibrary] with key [param name]. + Returns [code]true[/code] if the [AnimationMixer] stores an [AnimationLibrary] with key [param name]. </description> </method> <method name="remove_animation_library"> @@ -261,8 +273,13 @@ The number of possible simultaneous sounds for each of the assigned AudioStreamPlayers. For example, if this value is [code]32[/code] and the animation has two audio tracks, the two [AudioStreamPlayer]s assigned can play simultaneously up to [code]32[/code] voices each. </member> + <member name="callback_mode_discrete" type="int" setter="set_callback_mode_discrete" getter="get_callback_mode_discrete" enum="AnimationMixer.AnimationCallbackModeDiscrete" default="0"> + Ordinarily, tracks can be set to [constant Animation.UPDATE_DISCRETE] to update infrequently, usually when using nearest interpolation. + However, when blending with [constant Animation.UPDATE_CONTINUOUS] several results are considered. The [member callback_mode_discrete] specify it explicitly. See also [enum AnimationCallbackModeDiscrete]. + To make the blended results look good, it is recommended to set this to [constant ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS] to update every frame during blending. Other values exist for compatibility and they are fine if there is no blending, but not so, may produce artifacts. + </member> <member name="callback_mode_method" type="int" setter="set_callback_mode_method" getter="get_callback_mode_method" enum="AnimationMixer.AnimationCallbackModeMethod" default="0"> - The call mode to use for Call Method tracks. + The call mode used for "Call Method" tracks. </member> <member name="callback_mode_process" type="int" setter="set_callback_mode_process" getter="get_callback_mode_process" enum="AnimationMixer.AnimationCallbackModeProcess" default="1"> The process notification in which to update animations. @@ -284,7 +301,7 @@ If the track has type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_ROTATION_3D] or [constant Animation.TYPE_SCALE_3D] the transformation will be canceled visually, and the animation will appear to stay in place. See also [method get_root_motion_position], [method get_root_motion_rotation], [method get_root_motion_scale] and [RootMotionView]. </member> <member name="root_node" type="NodePath" setter="set_root_node" getter="get_root_node" default="NodePath("..")"> - The node from which node path references will travel. + The node which node path references will travel from. </member> </members> <signals> @@ -316,9 +333,14 @@ Notifies when the caches have been cleared, either automatically, or manually via [method clear_caches]. </description> </signal> + <signal name="mixer_applied"> + <description> + Notifies when the blending result related have been applied to the target objects. + </description> + </signal> <signal name="mixer_updated"> <description> - Editor only. Notifies when the property have been updated to update dummy [AnimationPlayer] in animation player editor. + Notifies when the property related process have been updated. </description> </signal> </signals> @@ -338,5 +360,15 @@ <constant name="ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE" value="1" enum="AnimationCallbackModeMethod"> Make method calls immediately when reached in the animation. </constant> + <constant name="ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT" value="0" enum="AnimationCallbackModeDiscrete"> + An [constant Animation.UPDATE_DISCRETE] track value takes precedence when blending [constant Animation.UPDATE_CONTINUOUS] or [constant Animation.UPDATE_CAPTURE] track values and [constant Animation.UPDATE_DISCRETE] track values. This is the default behavior for [AnimationPlayer]. + [b]Note:[/b] If a value track has non-numeric type key values, it is internally converted to use [constant ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT] with [constant Animation.UPDATE_DISCRETE]. + </constant> + <constant name="ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE" value="1" enum="AnimationCallbackModeDiscrete"> + An [constant Animation.UPDATE_CONTINUOUS] or [constant Animation.UPDATE_CAPTURE] track value takes precedence when blending the [constant Animation.UPDATE_CONTINUOUS] or [constant Animation.UPDATE_CAPTURE] track values and the [constant Animation.UPDATE_DISCRETE] track values. + </constant> + <constant name="ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS" value="2" enum="AnimationCallbackModeDiscrete"> + Always treat the [constant Animation.UPDATE_DISCRETE] track value as [constant Animation.UPDATE_CONTINUOUS] with [constant Animation.INTERPOLATION_NEAREST]. This is the default behavior for [AnimationTree]. + </constant> </constants> </class> diff --git a/doc/classes/AnimationNode.xml b/doc/classes/AnimationNode.xml index a028d0bb4f..960bbe68ad 100644 --- a/doc/classes/AnimationNode.xml +++ b/doc/classes/AnimationNode.xml @@ -6,6 +6,13 @@ <description> Base resource for [AnimationTree] nodes. In general, it's not used directly, but you can create custom ones with custom blending formulas. Inherit this when creating animation nodes mainly for use in [AnimationNodeBlendTree], otherwise [AnimationRootNode] should be used instead. + You can access the time information as read-only parameter which is processed and stored in the previous frame for all nodes except [AnimationNodeOutput]. + [b]Note:[/b] If more than two inputs exist in the [AnimationNode], which time information takes precedence depends on the type of [AnimationNode]. + [codeblock] + var current_length = $AnimationTree[parameters/AnimationNodeName/current_length] + var current_position = $AnimationTree[parameters/AnimationNodeName/current_position] + var current_delta = $AnimationTree[parameters/AnimationNodeName/current_delta] + [/codeblock] </description> <tutorials> <link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link> @@ -27,7 +34,7 @@ <method name="_get_child_nodes" qualifiers="virtual const"> <return type="Dictionary" /> <description> - When inheriting from [AnimationRootNode], implement this virtual method to return all children animation nodes in order as a [code]name: node[/code] dictionary. + When inheriting from [AnimationRootNode], implement this virtual method to return all child animation nodes in order as a [code]name: node[/code] dictionary. </description> </method> <method name="_get_parameter_default_value" qualifiers="virtual const"> @@ -56,7 +63,7 @@ When inheriting from [AnimationRootNode], implement this virtual method to return whether the [param parameter] is read-only. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. </description> </method> - <method name="_process" qualifiers="virtual const"> + <method name="_process" qualifiers="virtual const" deprecated="Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future."> <return type="float" /> <param index="0" name="time" type="float" /> <param index="1" name="seek" type="bool" /> @@ -65,7 +72,7 @@ <description> When inheriting from [AnimationRootNode], implement this virtual method to run some code when this animation node is processed. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute. Here, call the [method blend_input], [method blend_node] or [method blend_animation] functions. You can also use [method get_parameter] and [method set_parameter] to modify local memory. - This function should return the time left for the current animation to finish (if unsure, pass the value from the main blend being called). + This function should return the delta. </description> </method> <method name="add_input"> @@ -115,7 +122,7 @@ <param index="7" name="sync" type="bool" default="true" /> <param index="8" name="test_only" type="bool" default="false" /> <description> - Blend another animation node (in case this animation node contains children animation nodes). This function is only useful if you inherit from [AnimationRootNode] instead, else editors will not display your animation node for addition. + Blend another animation node (in case this animation node contains child animation nodes). This function is only useful if you inherit from [AnimationRootNode] instead, otherwise editors will not display your animation node for addition. </description> </method> <method name="find_input" qualifiers="const"> diff --git a/doc/classes/AnimationNodeAnimation.xml b/doc/classes/AnimationNodeAnimation.xml index d965d31b03..5683371182 100644 --- a/doc/classes/AnimationNodeAnimation.xml +++ b/doc/classes/AnimationNodeAnimation.xml @@ -15,9 +15,27 @@ <member name="animation" type="StringName" setter="set_animation" getter="get_animation" default="&"""> Animation to use as an output. It is one of the animations provided by [member AnimationTree.anim_player]. </member> + <member name="loop_mode" type="int" setter="set_loop_mode" getter="get_loop_mode" enum="Animation.LoopMode"> + If [member use_custom_timeline] is [code]true[/code], override the loop settings of the original [Animation] resource with the value. + </member> <member name="play_mode" type="int" setter="set_play_mode" getter="get_play_mode" enum="AnimationNodeAnimation.PlayMode" default="0"> Determines the playback direction of the animation. </member> + <member name="start_offset" type="float" setter="set_start_offset" getter="get_start_offset"> + If [member use_custom_timeline] is [code]true[/code], offset the start position of the animation. + This is useful for adjusting which foot steps first in 3D walking animations. + </member> + <member name="stretch_time_scale" type="bool" setter="set_stretch_time_scale" getter="is_stretching_time_scale"> + If [code]true[/code], scales the time so that the length specified in [member timeline_length] is one cycle. + This is useful for matching the periods of walking and running animations. + If [code]false[/code], the original animation length is respected. If you set the loop to [member loop_mode], the animation will loop in [member timeline_length]. + </member> + <member name="timeline_length" type="float" setter="set_timeline_length" getter="get_timeline_length"> + If [member use_custom_timeline] is [code]true[/code], offset the start position of the animation. + </member> + <member name="use_custom_timeline" type="bool" setter="set_use_custom_timeline" getter="is_using_custom_timeline" default="false"> + If [code]true[/code], [AnimationNode] provides an animation based on the [Animation] resource with some parameters adjusted. + </member> </members> <constants> <constant name="PLAY_MODE_FORWARD" value="0" enum="PlayMode"> diff --git a/doc/classes/AnimationNodeOneShot.xml b/doc/classes/AnimationNodeOneShot.xml index ac7cf70133..6ff2d6f6db 100644 --- a/doc/classes/AnimationNodeOneShot.xml +++ b/doc/classes/AnimationNodeOneShot.xml @@ -66,17 +66,22 @@ <member name="autorestart_random_delay" type="float" setter="set_autorestart_random_delay" getter="get_autorestart_random_delay" default="0.0"> If [member autorestart] is [code]true[/code], a random additional delay (in seconds) between 0 and this value will be added to [member autorestart_delay]. </member> + <member name="break_loop_at_end" type="bool" setter="set_break_loop_at_end" getter="is_loop_broken_at_end" default="false"> + If [code]true[/code], breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + </member> <member name="fadein_curve" type="Curve" setter="set_fadein_curve" getter="get_fadein_curve"> Determines how cross-fading between animations is eased. If empty, the transition will be linear. </member> <member name="fadein_time" type="float" setter="set_fadein_time" getter="get_fadein_time" default="0.0"> The fade-in duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a cross-fade that starts at 0 second and ends at 1 second during the animation. + [b]Note:[/b] [AnimationNodeOneShot] transitions the current state after the end of the fading. When [AnimationNodeOutput] is considered as the most upstream, so the [member fadein_time] is scaled depending on the downstream delta. For example, if this value is set to [code]1.0[/code] and a [AnimationNodeTimeScale] with a value of [code]2.0[/code] is chained downstream, the actual processing time will be 0.5 second. </member> <member name="fadeout_curve" type="Curve" setter="set_fadeout_curve" getter="get_fadeout_curve"> Determines how cross-fading between animations is eased. If empty, the transition will be linear. </member> <member name="fadeout_time" type="float" setter="set_fadeout_time" getter="get_fadeout_time" default="0.0"> The fade-out duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a cross-fade that starts at 4 second and ends at 5 second during the animation. + [b]Note:[/b] [AnimationNodeOneShot] transitions the current state after the end of the fading. When [AnimationNodeOutput] is considered as the most upstream, so the [member fadeout_time] is scaled depending on the downstream delta. For example, if this value is set to [code]1.0[/code] and an [AnimationNodeTimeScale] with a value of [code]2.0[/code] is chained downstream, the actual processing time will be 0.5 second. </member> <member name="mix_mode" type="int" setter="set_mix_mode" getter="get_mix_mode" enum="AnimationNodeOneShot.MixMode" default="0"> The blend type. diff --git a/doc/classes/AnimationNodeStateMachine.xml b/doc/classes/AnimationNodeStateMachine.xml index 0a1a7df2f4..86311542ad 100644 --- a/doc/classes/AnimationNodeStateMachine.xml +++ b/doc/classes/AnimationNodeStateMachine.xml @@ -143,6 +143,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="node" type="AnimationNode" /> <description> + Replaces the given animation node with a new animation node. </description> </method> <method name="set_graph_offset"> @@ -181,7 +182,7 @@ Seeking to the beginning is treated as seeking to the beginning of the animation in the current state. Transition to the end state, or the absence of transitions in each state, is treated as exiting the state machine. </constant> <constant name="STATE_MACHINE_TYPE_GROUPED" value="2" enum="StateMachineType"> - This is a grouped state machine that can be controlled from a parent state machine. It does not work on standalone. There must be a state machine with [member state_machine_type] of [constant STATE_MACHINE_TYPE_ROOT] or [constant STATE_MACHINE_TYPE_NESTED] in the parent or ancestor. + This is a grouped state machine that can be controlled from a parent state machine. It does not work independently. There must be a state machine with [member state_machine_type] of [constant STATE_MACHINE_TYPE_ROOT] or [constant STATE_MACHINE_TYPE_NESTED] in the parent or ancestor. </constant> </constants> </class> diff --git a/doc/classes/AnimationNodeStateMachineTransition.xml b/doc/classes/AnimationNodeStateMachineTransition.xml index 7b7797f594..7bd0bd7e7e 100644 --- a/doc/classes/AnimationNodeStateMachineTransition.xml +++ b/doc/classes/AnimationNodeStateMachineTransition.xml @@ -28,6 +28,9 @@ <member name="advance_mode" type="int" setter="set_advance_mode" getter="get_advance_mode" enum="AnimationNodeStateMachineTransition.AdvanceMode" default="1"> Determines whether the transition should disabled, enabled when using [method AnimationNodeStateMachinePlayback.travel], or traversed automatically if the [member advance_condition] and [member advance_expression] checks are true (if assigned). </member> + <member name="break_loop_at_end" type="bool" setter="set_break_loop_at_end" getter="is_loop_broken_at_end" default="false"> + If [code]true[/code], breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + </member> <member name="priority" type="int" setter="set_priority" getter="get_priority" default="1"> Lower priority transitions are preferred when travelling through the tree via [method AnimationNodeStateMachinePlayback.travel] or [member advance_mode] is set to [constant ADVANCE_MODE_AUTO]. </member> @@ -42,6 +45,7 @@ </member> <member name="xfade_time" type="float" setter="set_xfade_time" getter="get_xfade_time" default="0.0"> The time to cross-fade between this state and the next. + [b]Note:[/b] [AnimationNodeStateMachine] transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When [AnimationNodeOutput] is considered as the most upstream, so the [member xfade_time] is not scaled depending on the downstream delta. See also [member AnimationNodeOneShot.fadeout_time]. </member> </members> <signals> diff --git a/doc/classes/AnimationNodeTimeScale.xml b/doc/classes/AnimationNodeTimeScale.xml index d7d4814506..4cb8ccb962 100644 --- a/doc/classes/AnimationNodeTimeScale.xml +++ b/doc/classes/AnimationNodeTimeScale.xml @@ -4,7 +4,7 @@ A time-scaling animation node used in [AnimationTree]. </brief_description> <description> - Allows to scale the speed of the animation (or reverse it) in any children [AnimationNode]s. Setting it to [code]0.0[/code] will pause the animation. + Allows to scale the speed of the animation (or reverse it) in any child [AnimationNode]s. Setting it to [code]0.0[/code] will pause the animation. </description> <tutorials> <link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link> diff --git a/doc/classes/AnimationNodeTransition.xml b/doc/classes/AnimationNodeTransition.xml index 3e1a0a28b5..775a208735 100644 --- a/doc/classes/AnimationNodeTransition.xml +++ b/doc/classes/AnimationNodeTransition.xml @@ -42,6 +42,13 @@ <link title="Third Person Shooter Demo">https://godotengine.org/asset-library/asset/678</link> </tutorials> <methods> + <method name="is_input_loop_broken_at_end" qualifiers="const"> + <return type="bool" /> + <param index="0" name="input" type="int" /> + <description> + Returns whether the animation breaks the loop at the end of the loop cycle for transition. + </description> + </method> <method name="is_input_reset" qualifiers="const"> <return type="bool" /> <param index="0" name="input" type="int" /> @@ -64,6 +71,14 @@ Enables or disables auto-advance for the given [param input] index. If enabled, state changes to the next input after playing the animation once. If enabled for the last input state, it loops to the first. </description> </method> + <method name="set_input_break_loop_at_end"> + <return type="void" /> + <param index="0" name="input" type="int" /> + <param index="1" name="enable" type="bool" /> + <description> + If [code]true[/code], breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + </description> + </method> <method name="set_input_reset"> <return type="void" /> <param index="0" name="input" type="int" /> @@ -85,6 +100,7 @@ </member> <member name="xfade_time" type="float" setter="set_xfade_time" getter="get_xfade_time" default="0.0"> Cross-fading time (in seconds) between each animation connected to the inputs. + [b]Note:[/b] [AnimationNodeTransition] transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When [AnimationNodeOutput] is considered as the most upstream, so the [member xfade_time] is not scaled depending on the downstream delta. See also [member AnimationNodeOneShot.fadeout_time]. </member> </members> </class> diff --git a/doc/classes/AnimationPlayer.xml b/doc/classes/AnimationPlayer.xml index dda0187e8b..9d2d93b0f0 100644 --- a/doc/classes/AnimationPlayer.xml +++ b/doc/classes/AnimationPlayer.xml @@ -44,10 +44,10 @@ Returns the blend time (in seconds) between two animations, referenced by their keys. </description> </method> - <method name="get_method_call_mode" qualifiers="const" is_deprecated="true"> + <method name="get_method_call_mode" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_method] instead."> <return type="int" enum="AnimationPlayer.AnimationMethodCallMode" /> <description> - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeMethod]. + Returns the call mode used for "Call Method" tracks. </description> </method> <method name="get_playing_speed" qualifiers="const"> @@ -57,10 +57,10 @@ Returns a negative value if the current animation is playing backwards. </description> </method> - <method name="get_process_callback" qualifiers="const" is_deprecated="true"> + <method name="get_process_callback" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_process] instead."> <return type="int" enum="AnimationPlayer.AnimationProcessCallback" /> <description> - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. + Returns the process notification in which to update animations. </description> </method> <method name="get_queue"> @@ -69,10 +69,10 @@ Returns a list of the animation keys that are currently queued to play. </description> </method> - <method name="get_root" qualifiers="const" is_deprecated="true"> + <method name="get_root" qualifiers="const" deprecated="Use [member AnimationMixer.root_node] instead."> <return type="NodePath" /> <description> - For backward compatibility. See [member AnimationMixer.root_node]. + Returns the node which node path references will travel from. </description> </method> <method name="is_playing" qualifiers="const"> @@ -90,7 +90,7 @@ </method> <method name="play"> <return type="void" /> - <param index="0" name="name" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" default="&""" /> <param index="1" name="custom_blend" type="float" default="-1" /> <param index="2" name="custom_speed" type="float" default="1.0" /> <param index="3" name="from_end" type="bool" default="false" /> @@ -103,13 +103,33 @@ </method> <method name="play_backwards"> <return type="void" /> - <param index="0" name="name" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" default="&""" /> <param index="1" name="custom_blend" type="float" default="-1" /> <description> Plays the animation with key [param name] in reverse. This method is a shorthand for [method play] with [code]custom_speed = -1.0[/code] and [code]from_end = true[/code], so see its description for more information. </description> </method> + <method name="play_with_capture"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="duration" type="float" default="-1.0" /> + <param index="2" name="custom_blend" type="float" default="-1" /> + <param index="3" name="custom_speed" type="float" default="1.0" /> + <param index="4" name="from_end" type="bool" default="false" /> + <param index="5" name="trans_type" type="int" enum="Tween.TransitionType" default="0" /> + <param index="6" name="ease_type" type="int" enum="Tween.EaseType" default="0" /> + <description> + See [method AnimationMixer.capture]. It is almost the same as the following: + [codeblock] + capture(name, duration, trans_type, ease_type) + play(name, custom_blend, custom_speed, from_end) + [/codeblock] + If name is blank, it specifies [member assigned_animation]. + If [param duration] is a negative value, the duration is set to the interval between the current position and the first key, when [param from_end] is [code]true[/code], uses the interval between the current position and the last key instead. + [b]Note:[/b] The [param duration] takes [member speed_scale] into account, but [param custom_speed] does not, because the capture cache is interpolated with the blend result and the result may contain multiple animations. + </description> + </method> <method name="queue"> <return type="void" /> <param index="0" name="name" type="StringName" /> @@ -125,7 +145,7 @@ <param index="2" name="update_only" type="bool" default="false" /> <description> Seeks the animation to the [param seconds] point in time (in seconds). If [param update] is [code]true[/code], the animation updates too, otherwise it updates at process time. Events between the current frame and [param seconds] are skipped. - If [param update_only] is true, the method / audio / animation playback tracks will not be processed. + If [param update_only] is [code]true[/code], the method / audio / animation playback tracks will not be processed. [b]Note:[/b] Seeking to the end of the animation doesn't emit [signal AnimationMixer.animation_finished]. If you want to skip animation and emit the signal, use [method AnimationMixer.advance]. </description> </method> @@ -138,25 +158,25 @@ Specifies a blend time (in seconds) between two animations, referenced by their keys. </description> </method> - <method name="set_method_call_mode" is_deprecated="true"> + <method name="set_method_call_mode" deprecated="Use [member AnimationMixer.callback_mode_method] instead."> <return type="void" /> <param index="0" name="mode" type="int" enum="AnimationPlayer.AnimationMethodCallMode" /> <description> - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeMethod]. + Sets the call mode used for "Call Method" tracks. </description> </method> - <method name="set_process_callback" is_deprecated="true"> + <method name="set_process_callback" deprecated="Use [member AnimationMixer.callback_mode_process] instead."> <return type="void" /> <param index="0" name="mode" type="int" enum="AnimationPlayer.AnimationProcessCallback" /> <description> - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. + Sets the process notification in which to update animations. </description> </method> - <method name="set_root" is_deprecated="true"> + <method name="set_root" deprecated="Use [member AnimationMixer.root_node] instead."> <return type="void" /> <param index="0" name="path" type="NodePath" /> <description> - For backward compatibility. See [member AnimationMixer.root_node]. + Sets the node which node path references will travel from. </description> </method> <method name="stop"> @@ -215,20 +235,15 @@ </signal> </signals> <constants> - <constant name="ANIMATION_PROCESS_PHYSICS" value="0" enum="AnimationProcessCallback" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]. + <constant name="ANIMATION_PROCESS_PHYSICS" value="0" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]."> </constant> - <constant name="ANIMATION_PROCESS_IDLE" value="1" enum="AnimationProcessCallback" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE]. + <constant name="ANIMATION_PROCESS_IDLE" value="1" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE]."> </constant> - <constant name="ANIMATION_PROCESS_MANUAL" value="2" enum="AnimationProcessCallback" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL]. + <constant name="ANIMATION_PROCESS_MANUAL" value="2" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL]."> </constant> - <constant name="ANIMATION_METHOD_CALL_DEFERRED" value="0" enum="AnimationMethodCallMode" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED]. + <constant name="ANIMATION_METHOD_CALL_DEFERRED" value="0" enum="AnimationMethodCallMode" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED]."> </constant> - <constant name="ANIMATION_METHOD_CALL_IMMEDIATE" value="1" enum="AnimationMethodCallMode" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE]. + <constant name="ANIMATION_METHOD_CALL_IMMEDIATE" value="1" enum="AnimationMethodCallMode" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE]."> </constant> </constants> </class> diff --git a/doc/classes/AnimationTree.xml b/doc/classes/AnimationTree.xml index 79e84192df..d240a4967e 100644 --- a/doc/classes/AnimationTree.xml +++ b/doc/classes/AnimationTree.xml @@ -12,17 +12,17 @@ <link title="Third Person Shooter Demo">https://godotengine.org/asset-library/asset/678</link> </tutorials> <methods> - <method name="get_process_callback" qualifiers="const" is_deprecated="true"> + <method name="get_process_callback" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_process] instead."> <return type="int" enum="AnimationTree.AnimationProcessCallback" /> <description> - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. + Returns the process notification in which to update animations. </description> </method> - <method name="set_process_callback" is_deprecated="true"> + <method name="set_process_callback" deprecated="Use [member AnimationMixer.callback_mode_process] instead."> <return type="void" /> <param index="0" name="mode" type="int" enum="AnimationTree.AnimationProcessCallback" /> <description> - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. + Sets the process notification in which to update animations. </description> </method> </methods> @@ -33,6 +33,7 @@ <member name="anim_player" type="NodePath" setter="set_animation_player" getter="get_animation_player" default="NodePath("")"> The path to the [AnimationPlayer] used for animating. </member> + <member name="callback_mode_discrete" type="int" setter="set_callback_mode_discrete" getter="get_callback_mode_discrete" overrides="AnimationMixer" enum="AnimationMixer.AnimationCallbackModeDiscrete" default="2" /> <member name="deterministic" type="bool" setter="set_deterministic" getter="is_deterministic" overrides="AnimationMixer" default="true" /> <member name="tree_root" type="AnimationRootNode" setter="set_tree_root" getter="get_tree_root"> The root animation node of this [AnimationTree]. See [AnimationRootNode]. @@ -46,14 +47,11 @@ </signal> </signals> <constants> - <constant name="ANIMATION_PROCESS_PHYSICS" value="0" enum="AnimationProcessCallback" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]. + <constant name="ANIMATION_PROCESS_PHYSICS" value="0" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]."> </constant> - <constant name="ANIMATION_PROCESS_IDLE" value="1" enum="AnimationProcessCallback" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE]. + <constant name="ANIMATION_PROCESS_IDLE" value="1" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE]."> </constant> - <constant name="ANIMATION_PROCESS_MANUAL" value="2" enum="AnimationProcessCallback" is_deprecated="true"> - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL]. + <constant name="ANIMATION_PROCESS_MANUAL" value="2" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL]."> </constant> </constants> </class> diff --git a/doc/classes/Area2D.xml b/doc/classes/Area2D.xml index 6fa8e4ae9f..a52aa80606 100644 --- a/doc/classes/Area2D.xml +++ b/doc/classes/Area2D.xml @@ -1,11 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="Area2D" inherits="CollisionObject2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="Area2D" inherits="CollisionObject2D" keywords="trigger" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A region of 2D space that detects other [CollisionObject2D]s entering or exiting it. </brief_description> <description> [Area2D] is a region of 2D space defined by one or multiple [CollisionShape2D] or [CollisionPolygon2D] child nodes. It detects when other [CollisionObject2D]s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. + [b]Note:[/b] Areas and bodies created with [PhysicsServer2D] might not interact as expected with [Area2D]s, and might not emit signals or track objects correctly. </description> <tutorials> <link title="Using Area2D">$DOCS_URL/tutorials/physics/using_area_2d.html</link> diff --git a/doc/classes/Area3D.xml b/doc/classes/Area3D.xml index 4f89e9b015..671c824c30 100644 --- a/doc/classes/Area3D.xml +++ b/doc/classes/Area3D.xml @@ -1,11 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="Area3D" inherits="CollisionObject3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="Area3D" inherits="CollisionObject3D" keywords="trigger" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A region of 3D space that detects other [CollisionObject3D]s entering or exiting it. </brief_description> <description> [Area3D] is a region of 3D space defined by one or multiple [CollisionShape3D] or [CollisionPolygon3D] child nodes. It detects when other [CollisionObject3D]s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. + [b]Note:[/b] Areas and bodies created with [PhysicsServer3D] might not interact as expected with [Area3D]s, and might not emit signals or track objects correctly. [b]Warning:[/b] Using a [ConcavePolygonShape3D] inside a [CollisionShape3D] child of this node (created e.g. by using the [b]Create Trimesh Collision Sibling[/b] option in the [b]Mesh[/b] menu that appears when selecting a [MeshInstance3D] node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple [ConvexPolygonShape3D]s or primitive shapes like [BoxShape3D], or in some cases it may be replaceable by a [CollisionPolygon3D]. </description> <tutorials> diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 87d303b476..c57256ba85 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -219,6 +219,11 @@ <param index="1" name="before" type="bool" default="true" /> <description> Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a [param before] specifier can be passed. If [code]false[/code], the returned index comes after all existing entries of the value in the array. + [codeblock] + var array = ["a", "b", "c", "c", "d", "e"] + print(array.bsearch("c", true)) # Prints 2, at the first matching element. + print(array.bsearch("c", false)) # Prints 4, after the last matching element, pointing to "d". + [/codeblock] [b]Note:[/b] Calling [method bsearch] on an unsorted array results in unexpected behavior. </description> </method> @@ -229,6 +234,7 @@ <param index="2" name="before" type="bool" default="true" /> <description> Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a [param before] specifier can be passed. If [code]false[/code], the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return [code]true[/code] if the first argument is less than the second, and return [code]false[/code] otherwise. + [b]Note:[/b] The custom method must accept the two arguments in any order, you cannot rely on that the first argument will always be from the array. [b]Note:[/b] Calling [method bsearch_custom] on an unsorted array results in unexpected behavior. </description> </method> @@ -333,7 +339,7 @@ Returns the script associated with a typed array tied to a class name. </description> </method> - <method name="has" qualifiers="const"> + <method name="has" qualifiers="const" keywords="includes, contains"> <return type="bool" /> <param index="0" name="value" type="Variant" /> <description> @@ -480,7 +486,7 @@ <return type="Variant" /> <param index="0" name="position" type="int" /> <description> - Removes and returns the element of the array at index [param position]. If negative, [param position] is considered relative to the end of the array. Leaves the array untouched and returns [code]null[/code] if the array is empty or if it's accessed out of bounds. An error message is printed when the array is accessed out of bounds, but not when the array is empty. + Removes and returns the element of the array at index [param position]. If negative, [param position] is considered relative to the end of the array. Leaves the array unchanged and returns [code]null[/code] if the array is empty or if it's accessed out of bounds. An error message is printed when the array is accessed out of bounds, but not when the array is empty. [b]Note:[/b] On large arrays, this method can be slower than [method pop_back] as it will reindex the array's elements that are located after the removed element. The larger the array and the lower the index of the removed element, the slower [method pop_at] will be. </description> </method> @@ -545,6 +551,7 @@ <param index="0" name="size" type="int" /> <description> Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are [code]null[/code]. Returns [constant OK] on success, or one of the other [enum Error] values if the operation failed. + Calling [method resize] once and assigning the new values is faster than adding new elements one by one. [b]Note:[/b] This method acts in-place and doesn't return a modified array. </description> </method> diff --git a/doc/classes/ArrayMesh.xml b/doc/classes/ArrayMesh.xml index dde7153d5f..0f6bf89cd7 100644 --- a/doc/classes/ArrayMesh.xml +++ b/doc/classes/ArrayMesh.xml @@ -71,7 +71,7 @@ Surfaces are created to be rendered using a [param primitive], which may be any of the values defined in [enum Mesh.PrimitiveType]. The [param arrays] argument is an array of arrays. Each of the [constant Mesh.ARRAY_MAX] elements contains an array with some of the mesh data for this surface as described by the corresponding member of [enum Mesh.ArrayType] or [code]null[/code] if it is not used by the surface. For example, [code]arrays[0][/code] is the array of vertices. That first vertex sub-array is always required; the others are optional. Adding an index array puts this surface into "index mode" where the vertex and other arrays become the sources of data and the index array defines the vertex order. All sub-arrays must have the same length as the vertex array (or be an exact multiple of the vertex array's length, when multiple elements of a sub-array correspond to a single vertex) or be empty, except for [constant Mesh.ARRAY_INDEX] if it is used. The [param blend_shapes] argument is an array of vertex data for each blend shape. Each element is an array of the same structure as [param arrays], but [constant Mesh.ARRAY_VERTEX], [constant Mesh.ARRAY_NORMAL], and [constant Mesh.ARRAY_TANGENT] are set if and only if they are set in [param arrays] and all other entries are [code]null[/code]. - The [param lods] argument is a dictionary with [float] keys and [PackedInt32Array] values. Each entry in the dictionary represents a LOD level of the surface, where the value is the [constant Mesh.ARRAY_INDEX] array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of a LOD also increases the distance that the objects has to be from the camera before the LOD is used. + The [param lods] argument is a dictionary with [float] keys and [PackedInt32Array] values. Each entry in the dictionary represents an LOD level of the surface, where the value is the [constant Mesh.ARRAY_INDEX] array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used. The [param flags] argument is the bitwise or of, as required: One value of [enum Mesh.ArrayCustomFormat] left shifted by [code]ARRAY_FORMAT_CUSTOMn_SHIFT[/code] for each custom channel in use, [constant Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE], [constant Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS], or [constant Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY]. [b]Note:[/b] When using indices, it is recommended to only use points, lines, or triangles. </description> diff --git a/doc/classes/AudioEffect.xml b/doc/classes/AudioEffect.xml index f0e8b4f19e..4fe47ac011 100644 --- a/doc/classes/AudioEffect.xml +++ b/doc/classes/AudioEffect.xml @@ -1,18 +1,33 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="AudioEffect" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Audio effect for audio. + Base class for audio effect resources. </brief_description> <description> - Base resource for audio bus. Applies an audio effect on the bus that the resource is applied on. + The base [Resource] for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through [method AudioServer.add_bus_effect], [method AudioServer.remove_bus_effect], and [method AudioServer.get_bus_effect]. + When applied on a bus, an audio effect creates a corresponding [AudioEffectInstance]. The instance is directly responsible for manipulating the sound, based on the original audio effect's properties. </description> <tutorials> + <link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link> <link title="Audio Mic Record Demo">https://godotengine.org/asset-library/asset/527</link> </tutorials> <methods> <method name="_instantiate" qualifiers="virtual"> <return type="AudioEffectInstance" /> <description> + Override this method to customize the [AudioEffectInstance] created when this effect is applied on a bus in the editor's Audio panel, or through [method AudioServer.add_bus_effect]. + [codeblock] + extends AudioEffect + + @export var strength = 4.0 + + func _instantiate(): + var effect = CustomAudioEffectInstance.new() + effect.base = self + + return effect + [/codeblock] + [b]Note:[/b] It is recommended to keep a reference to the original [AudioEffect] in the new instance. Depending on the implementation this allows the effect instance to listen for changes at run-time and be modified accordingly. </description> </method> </methods> diff --git a/doc/classes/AudioEffectCapture.xml b/doc/classes/AudioEffectCapture.xml index 275e5ab0b6..ce516be5fc 100644 --- a/doc/classes/AudioEffectCapture.xml +++ b/doc/classes/AudioEffectCapture.xml @@ -5,12 +5,11 @@ </brief_description> <description> AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer. - Application code should consume these audio frames from this ring buffer using [method get_buffer] and process it as needed, for example to capture data from an [AudioStreamMicrophone], implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating point PCM. - [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + Application code should consume these audio frames from this ring buffer using [method get_buffer] and process it as needed, for example to capture data from an [AudioStreamMicrophone], implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating-point PCM. + Unlike [AudioEffectRecord], this effect only returns the raw audio samples instead of encoding them into an [AudioStream]. </description> <tutorials> <link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link> - <link title="Audio Mic Record Demo">https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record</link> </tutorials> <methods> <method name="can_get_buffer" qualifiers="const"> @@ -24,6 +23,7 @@ <return type="void" /> <description> Clears the internal ring buffer. + [b]Note:[/b] Calling this during a capture can cause the loss of samples which causes popping in the playback. </description> </method> <method name="get_buffer"> @@ -32,6 +32,7 @@ <description> Gets the next [param frames] audio samples from the internal ring buffer. Returns a [PackedVector2Array] containing exactly [param frames] audio samples if available, or an empty [PackedVector2Array] if insufficient data was available. + The samples are signed floating-point PCM between [code]-1[/code] and [code]1[/code]. You will have to scale them if you want to use them as 8 or 16-bit integer samples. ([code]v = 0x7fff * samples[0].x[/code]) </description> </method> <method name="get_buffer_length_frames" qualifiers="const"> diff --git a/doc/classes/AudioEffectHardLimiter.xml b/doc/classes/AudioEffectHardLimiter.xml new file mode 100644 index 0000000000..7616b91f97 --- /dev/null +++ b/doc/classes/AudioEffectHardLimiter.xml @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="AudioEffectHardLimiter" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Adds a hard limiter audio effect to an Audio bus. + </brief_description> + <description> + A limiter is an effect designed to disallow sound from going over a given dB threshold. Hard limiters predict volume peaks, and will smoothly apply gain reduction when a peak crosses the ceiling threshold to prevent clipping and distortion. It preserves the waveform and prevents it from crossing the ceiling threshold. Adding one in the Master bus is recommended as a safety measure to prevent sudden volume peaks from occurring, and to prevent distortion caused by clipping. + </description> + <tutorials> + <link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link> + </tutorials> + <members> + <member name="ceiling_db" type="float" setter="set_ceiling_db" getter="get_ceiling_db" default="-0.3"> + The waveform's maximum allowed value, in decibels. This value can range from [code]-24.0[/code] to [code]0.0[/code]. + The default value of [code]-0.3[/code] prevents potential inter-sample peaks (ISP) from crossing over 0 dB, which can cause slight distortion on some older hardware. + </member> + <member name="pre_gain_db" type="float" setter="set_pre_gain_db" getter="get_pre_gain_db" default="0.0"> + Gain to apply before limiting, in decibels. + </member> + <member name="release" type="float" setter="set_release" getter="get_release" default="0.1"> + Time it takes in seconds for the gain reduction to fully release. + </member> + </members> +</class> diff --git a/doc/classes/AudioEffectInstance.xml b/doc/classes/AudioEffectInstance.xml index 3e868ae9da..0f3ae11793 100644 --- a/doc/classes/AudioEffectInstance.xml +++ b/doc/classes/AudioEffectInstance.xml @@ -1,10 +1,13 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="AudioEffectInstance" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Manipulates the audio it receives for a given effect. </brief_description> <description> + An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an [AudioEffect] when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with [method AudioServer.get_bus_effect_instance]. </description> <tutorials> + <link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link> </tutorials> <methods> <method name="_process" qualifiers="virtual"> @@ -13,11 +16,15 @@ <param index="1" name="dst_buffer" type="AudioFrame*" /> <param index="2" name="frame_count" type="int" /> <description> + Called by the [AudioServer] to process this effect. When [method _process_silence] is not overridden or it returns [code]false[/code], this method is called only when the bus is active. + [b]Note:[/b] It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. </description> </method> <method name="_process_silence" qualifiers="virtual const"> <return type="bool" /> <description> + Override this method to customize the processing behavior of this effect instance. + Should return [code]true[/code] to force the [AudioServer] to always call [method _process], even if the bus has been muted or cannot otherwise be heard. </description> </method> </methods> diff --git a/doc/classes/AudioEffectLimiter.xml b/doc/classes/AudioEffectLimiter.xml index 57861d0485..b1a80cd9ef 100644 --- a/doc/classes/AudioEffectLimiter.xml +++ b/doc/classes/AudioEffectLimiter.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AudioEffectLimiter" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AudioEffectLimiter" inherits="AudioEffect" deprecated="Use [AudioEffectHardLimiter] instead." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Adds a soft-clip limiter audio effect to an Audio bus. </brief_description> diff --git a/doc/classes/AudioEffectPitchShift.xml b/doc/classes/AudioEffectPitchShift.xml index ec60e6a75a..4d4baa34ab 100644 --- a/doc/classes/AudioEffectPitchShift.xml +++ b/doc/classes/AudioEffectPitchShift.xml @@ -18,7 +18,7 @@ The oversampling factor to use. Higher values result in better quality, but are more demanding on the CPU and may cause audio cracking if the CPU can't keep up. </member> <member name="pitch_scale" type="float" setter="set_pitch_scale" getter="get_pitch_scale" default="1.0"> - The pitch scale to use. [code]1.0[/code] is the default pitch and plays sounds unaltered. [member pitch_scale] can range from [code]0.0[/code] (infinitely low pitch, inaudible) to [code]16[/code] (16 times higher than the initial pitch). + The pitch scale to use. [code]1.0[/code] is the default pitch and plays sounds unaffected. [member pitch_scale] can range from [code]0.0[/code] (infinitely low pitch, inaudible) to [code]16[/code] (16 times higher than the initial pitch). </member> </members> <constants> diff --git a/doc/classes/AudioEffectRecord.xml b/doc/classes/AudioEffectRecord.xml index e07d66fa7b..5b43c5ebaa 100644 --- a/doc/classes/AudioEffectRecord.xml +++ b/doc/classes/AudioEffectRecord.xml @@ -4,9 +4,10 @@ Audio effect used for recording the sound from an audio bus. </brief_description> <description> - Allows the user to record the sound from an audio bus. This can include all audio output by Godot when used on the "Master" audio bus. + Allows the user to record the sound from an audio bus into an [AudioStreamWAV]. When used on the "Master" audio bus, this includes all audio output by Godot. + Unlike [AudioEffectCapture], this effect encodes the recording with the given format (8-bit, 16-bit, or compressed) instead of giving access to the raw audio samples. Can be used (with an [AudioStreamMicrophone]) to record from a microphone. - It sets and gets the format in which the audio file will be recorded (8-bit, 16-bit, or compressed). It checks whether or not the recording is active, and if it is, records the sound. It then returns the recorded sample. + [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. </description> <tutorials> <link title="Recording with microphone">$DOCS_URL/tutorials/audio/recording_with_microphone.html</link> diff --git a/doc/classes/AudioListener2D.xml b/doc/classes/AudioListener2D.xml index 8328e82dbd..85505438e7 100644 --- a/doc/classes/AudioListener2D.xml +++ b/doc/classes/AudioListener2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AudioListener2D" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AudioListener2D" inherits="Node2D" keywords="sound" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Overrides the location sounds are heard from. </brief_description> diff --git a/doc/classes/AudioListener3D.xml b/doc/classes/AudioListener3D.xml index a5fe0153c4..c9de089195 100644 --- a/doc/classes/AudioListener3D.xml +++ b/doc/classes/AudioListener3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AudioListener3D" inherits="Node3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AudioListener3D" inherits="Node3D" keywords="sound" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Overrides the location sounds are heard from. </brief_description> diff --git a/doc/classes/AudioServer.xml b/doc/classes/AudioServer.xml index 21ad817c6c..993aa581dc 100644 --- a/doc/classes/AudioServer.xml +++ b/doc/classes/AudioServer.xml @@ -281,6 +281,8 @@ <return type="void" /> <param index="0" name="enable" type="bool" /> <description> + If set to [code]true[/code], all instances of [AudioStreamPlayback] will call [method AudioStreamPlayback._tag_used_streams] every mix step. + [b]Note:[/b] This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews. </description> </method> <method name="swap_bus_effects"> @@ -311,7 +313,7 @@ Name of the current device for audio output (see [method get_output_device_list]). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value [code]"Default"[/code] will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code]. </member> <member name="playback_speed_scale" type="float" setter="set_playback_speed_scale" getter="get_playback_speed_scale" default="1.0"> - Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). + Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). See also [member Engine.time_scale] to affect the general simulation speed, which is independent from [member AudioServer.playback_speed_scale]. </member> </members> <signals> diff --git a/doc/classes/AudioStream.xml b/doc/classes/AudioStream.xml index 12e09b235f..9813c2f251 100644 --- a/doc/classes/AudioStream.xml +++ b/doc/classes/AudioStream.xml @@ -16,31 +16,45 @@ <method name="_get_beat_count" qualifiers="virtual const"> <return type="int" /> <description> + Overridable method. Should return the total number of beats of this audio stream. Used by the engine to determine the position of every beat. + Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example). </description> </method> <method name="_get_bpm" qualifiers="virtual const"> <return type="float" /> <description> + Overridable method. Should return the tempo of this audio stream, in beats per minute (BPM). Used by the engine to determine the position of every beat. + Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example). </description> </method> <method name="_get_length" qualifiers="virtual const"> <return type="float" /> <description> + Override this method to customize the returned value of [method get_length]. Should return the length of this audio stream, in seconds. + </description> + </method> + <method name="_get_parameter_list" qualifiers="virtual const"> + <return type="Dictionary[]" /> + <description> + Return the controllable parameters of this stream. This array contains dictionaries with a property info description format (see [method Object.get_property_list]). Additionally, the default value for this parameter must be added tho each dictionary in "default_value" field. </description> </method> <method name="_get_stream_name" qualifiers="virtual const"> <return type="String" /> <description> + Override this method to customize the name assigned to this audio stream. Unused by the engine. </description> </method> <method name="_instantiate_playback" qualifiers="virtual const"> <return type="AudioStreamPlayback" /> <description> + Override this method to customize the returned value of [method instantiate_playback]. Should returned a new [AudioStreamPlayback] created when the stream is played (such as by an [AudioStreamPlayer]).. </description> </method> <method name="_is_monophonic" qualifiers="virtual const"> <return type="bool" /> <description> + Override this method to customize the returned value of [method is_monophonic]. Should return [code]true[/code] if this audio stream only supports one channel. </description> </method> <method name="get_length" qualifiers="const"> @@ -52,14 +66,21 @@ <method name="instantiate_playback"> <return type="AudioStreamPlayback" /> <description> - Returns an AudioStreamPlayback. Useful for when you want to extend [method _instantiate_playback] but call [method instantiate_playback] from an internally held AudioStream subresource. An example of this can be found in the source files for [code]AudioStreamRandomPitch::instantiate_playback[/code]. + Returns a newly created [AudioStreamPlayback] intended to play this audio stream. Useful for when you want to extend [method _instantiate_playback] but call [method instantiate_playback] from an internally held AudioStream subresource. An example of this can be found in the source code for [code]AudioStreamRandomPitch::instantiate_playback[/code]. </description> </method> <method name="is_monophonic" qualifiers="const"> <return type="bool" /> <description> - Returns true if this audio stream only supports monophonic playback, or false if the audio stream supports polyphony. + Returns [code]true[/code] if this audio stream only supports one channel ([i]monophony[/i]), or [code]false[/code] if the audio stream supports two or more channels ([i]polyphony[/i]). </description> </method> </methods> + <signals> + <signal name="parameter_list_changed"> + <description> + Signal to be emitted to notify when the parameter list changed. + </description> + </signal> + </signals> </class> diff --git a/doc/classes/AudioStreamPlayback.xml b/doc/classes/AudioStreamPlayback.xml index 7692690b5e..460a7050c8 100644 --- a/doc/classes/AudioStreamPlayback.xml +++ b/doc/classes/AudioStreamPlayback.xml @@ -13,16 +13,26 @@ <method name="_get_loop_count" qualifiers="virtual const"> <return type="int" /> <description> + Overridable method. Should return how many times this audio stream has looped. Most built-in playbacks always return [code]0[/code]. + </description> + </method> + <method name="_get_parameter" qualifiers="virtual const"> + <return type="Variant" /> + <param index="0" name="name" type="StringName" /> + <description> + Return the current value of a playback parameter by name (see [method AudioStream._get_parameter_list]). </description> </method> <method name="_get_playback_position" qualifiers="virtual const"> <return type="float" /> <description> + Overridable method. Should return the current progress along the audio stream, in seconds. </description> </method> <method name="_is_playing" qualifiers="virtual const"> <return type="bool" /> <description> + Overridable method. Should return [code]true[/code] if this playback is active and playing its audio stream. </description> </method> <method name="_mix" qualifiers="virtual"> @@ -31,28 +41,42 @@ <param index="1" name="rate_scale" type="float" /> <param index="2" name="frames" type="int" /> <description> + Override this method to customize how the audio stream is mixed. This method is called even if the playback is not active. + [b]Note:[/b] It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. </description> </method> <method name="_seek" qualifiers="virtual"> <return type="void" /> <param index="0" name="position" type="float" /> <description> + Override this method to customize what happens when seeking this audio stream at the given [param position], such as by calling [method AudioStreamPlayer.seek]. + </description> + </method> + <method name="_set_parameter" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="value" type="Variant" /> + <description> + Set the current value of a playback parameter by name (see [method AudioStream._get_parameter_list]). </description> </method> <method name="_start" qualifiers="virtual"> <return type="void" /> <param index="0" name="from_pos" type="float" /> <description> + Override this method to customize what happens when the playback starts at the given position, such as by calling [method AudioStreamPlayer.play]. </description> </method> <method name="_stop" qualifiers="virtual"> <return type="void" /> <description> + Override this method to customize what happens when the playback is stopped, such as by calling [method AudioStreamPlayer.stop]. </description> </method> <method name="_tag_used_streams" qualifiers="virtual"> <return type="void" /> <description> + Overridable method. Called whenever the audio stream is mixed if the playback is active and [method AudioServer.set_enable_tagging_used_audio_streams] has been set to [code]true[/code]. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview. </description> </method> </methods> diff --git a/doc/classes/AudioStreamPlayer.xml b/doc/classes/AudioStreamPlayer.xml index ac50a5ee30..fbe2508da3 100644 --- a/doc/classes/AudioStreamPlayer.xml +++ b/doc/classes/AudioStreamPlayer.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AudioStreamPlayer" inherits="Node" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AudioStreamPlayer" inherits="Node" keywords="sound, music, song" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Plays back audio non-positionally. </brief_description> diff --git a/doc/classes/AudioStreamPlayer2D.xml b/doc/classes/AudioStreamPlayer2D.xml index 77a038c5fa..8b81887976 100644 --- a/doc/classes/AudioStreamPlayer2D.xml +++ b/doc/classes/AudioStreamPlayer2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AudioStreamPlayer2D" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AudioStreamPlayer2D" inherits="Node2D" keywords="sound, sfx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Plays positional sound in 2D space. </brief_description> diff --git a/doc/classes/AudioStreamPlayer3D.xml b/doc/classes/AudioStreamPlayer3D.xml index f4c9adcaec..af92fd4a44 100644 --- a/doc/classes/AudioStreamPlayer3D.xml +++ b/doc/classes/AudioStreamPlayer3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AudioStreamPlayer3D" inherits="Node3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AudioStreamPlayer3D" inherits="Node3D" keywords="sound, sfx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Plays positional sound in 3D space. </brief_description> diff --git a/doc/classes/AudioStreamWAV.xml b/doc/classes/AudioStreamWAV.xml index c3df946b4b..206b6361cc 100644 --- a/doc/classes/AudioStreamWAV.xml +++ b/doc/classes/AudioStreamWAV.xml @@ -8,6 +8,7 @@ This class can also be used to store dynamically-generated PCM audio data. See also [AudioStreamGenerator] for procedural audio generation. </description> <tutorials> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="save_to_wav"> diff --git a/doc/classes/BaseButton.xml b/doc/classes/BaseButton.xml index c5998ad8a1..764f4a65b5 100644 --- a/doc/classes/BaseButton.xml +++ b/doc/classes/BaseButton.xml @@ -59,7 +59,7 @@ If [code]true[/code], the button's state is pressed. Means the button is pressed down or toggled (if [member toggle_mode] is active). Only works if [member toggle_mode] is [code]true[/code]. [b]Note:[/b] Setting [member button_pressed] will result in [signal toggled] to be emitted. If you want to change the pressed state without emitting that signal, use [method set_pressed_no_signal]. </member> - <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false"> + <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled"> If [code]true[/code], the button is in disabled state and can't be clicked or toggled. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index c3295d854f..1bd4183b3c 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -57,19 +57,19 @@ </method> </methods> <members> - <member name="albedo_color" type="Color" setter="set_albedo" getter="get_albedo" default="Color(1, 1, 1, 1)"> + <member name="albedo_color" type="Color" setter="set_albedo" getter="get_albedo" default="Color(1, 1, 1, 1)" keywords="albedo_colour, diffuse_color, diffuse_colour"> The material's base color. [b]Note:[/b] If [member detail_enabled] is [code]true[/code] and a [member detail_albedo] texture is specified, [member albedo_color] will [i]not[/i] modulate the detail texture. This can be used to color partial areas of a material by not specifying an albedo texture and using a transparent [member detail_albedo] texture instead. </member> - <member name="albedo_texture" type="Texture2D" setter="set_texture" getter="get_texture"> + <member name="albedo_texture" type="Texture2D" setter="set_texture" getter="get_texture" keywords="diffuse_texture"> Texture to multiply by [member albedo_color]. Used for basic texturing of objects. If the texture appears unexpectedly too dark or too bright, check [member albedo_texture_force_srgb]. </member> - <member name="albedo_texture_force_srgb" type="bool" setter="set_flag" getter="get_flag" default="false"> + <member name="albedo_texture_force_srgb" type="bool" setter="set_flag" getter="get_flag" default="false" keywords="diffuse_texture_force_srgb"> If [code]true[/code], forces a conversion of the [member albedo_texture] from sRGB color space to linear color space. See also [member vertex_color_is_srgb]. This should only be enabled when needed (typically when using a [ViewportTexture] as [member albedo_texture]). If [member albedo_texture_force_srgb] is [code]true[/code] when it shouldn't be, the texture will appear to be too dark. If [member albedo_texture_force_srgb] is [code]false[/code] when it shouldn't be, the texture will appear to be too bright. </member> - <member name="albedo_texture_msdf" type="bool" setter="set_flag" getter="get_flag" default="false"> + <member name="albedo_texture_msdf" type="bool" setter="set_flag" getter="get_flag" default="false" keywords="diffuse_texture_force_srgb"> Enables multichannel signed distance field rendering shader. Use [member msdf_pixel_range] and [member msdf_outline_size] to configure MSDF parameters. </member> <member name="alpha_antialiasing_edge" type="float" setter="set_alpha_antialiasing_edge" getter="get_alpha_antialiasing_edge"> @@ -81,7 +81,7 @@ <member name="alpha_hash_scale" type="float" setter="set_alpha_hash_scale" getter="get_alpha_hash_scale"> The hashing scale for Alpha Hash. Recommended values between [code]0[/code] and [code]2[/code]. </member> - <member name="alpha_scissor_threshold" type="float" setter="set_alpha_scissor_threshold" getter="get_alpha_scissor_threshold"> + <member name="alpha_scissor_threshold" type="float" setter="set_alpha_scissor_threshold" getter="get_alpha_scissor_threshold" keywords="alpha_test_threshold"> Threshold at which the alpha scissor will discard values. Higher values will result in more pixels being discarded. If the material becomes too opaque at a distance, try increasing [member alpha_scissor_threshold]. If the material disappears at a distance, try decreasing [member alpha_scissor_threshold]. </member> <member name="anisotropy" type="float" setter="set_anisotropy" getter="get_anisotropy" default="0.0"> @@ -125,6 +125,7 @@ </member> <member name="billboard_mode" type="int" setter="set_billboard_mode" getter="get_billboard_mode" enum="BaseMaterial3D.BillboardMode" default="0"> Controls how the object faces the camera. See [enum BillboardMode]. + [b]Note:[/b] When billboarding is enabled and the material also casts shadows, billboards will face [b]the[/b] camera in the scene when rendering shadows. In scenes with multiple cameras, the intended shadow cannot be determined and this will result in undefined behavior. See [url=https://github.com/godotengine/godot/pull/72638]GitHub Pull Request #72638[/url] for details. [b]Note:[/b] Billboard mode is not suitable for VR because the left-right vector of the camera is not horizontal when the screen is attached to your head instead of on the table. See [url=https://github.com/godotengine/godot/issues/41567]GitHub issue #41567[/url] for details. </member> <member name="blend_mode" type="int" setter="set_blend_mode" getter="get_blend_mode" enum="BaseMaterial3D.BlendMode" default="0"> @@ -383,7 +384,7 @@ If [code]true[/code], enables subsurface scattering transmittance. Only effective if [member subsurf_scatter_enabled] is [code]true[/code]. See also [member backlight_enabled]. </member> <member name="subsurf_scatter_transmittance_texture" type="Texture2D" setter="set_texture" getter="get_texture"> - The texture to use for multiplying the intensity of the subsurface scattering transmitteance intensity. See also [member subsurf_scatter_texture]. Ignored if [member subsurf_scatter_skin_mode] is [code]true[/code]. + The texture to use for multiplying the intensity of the subsurface scattering transmittance intensity. See also [member subsurf_scatter_texture]. Ignored if [member subsurf_scatter_skin_mode] is [code]true[/code]. </member> <member name="texture_filter" type="int" setter="set_texture_filter" getter="get_texture_filter" enum="BaseMaterial3D.TextureFilter" default="3"> Filter flags for the texture. See [enum TextureFilter] for options. @@ -501,22 +502,22 @@ Represents the size of the [enum TextureParam] enum. </constant> <constant name="TEXTURE_FILTER_NEAREST" value="0" enum="TextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_LINEAR" value="1" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="2" enum="TextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="3" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for most cases as mipmaps are important to smooth out pixels that are far from the camera. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC" value="4" enum="TextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC" value="5" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. </constant> <constant name="TEXTURE_FILTER_MAX" value="6" enum="TextureFilter"> Represents the size of the [enum TextureFilter] enum. @@ -533,7 +534,7 @@ <constant name="TRANSPARENCY_ALPHA" value="1" enum="Transparency"> The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting. </constant> - <constant name="TRANSPARENCY_ALPHA_SCISSOR" value="2" enum="Transparency"> + <constant name="TRANSPARENCY_ALPHA_SCISSOR" value="2" enum="Transparency" keywords="TRANSPARENCY_ALPHA_TEST"> The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. </constant> <constant name="TRANSPARENCY_ALPHA_HASH" value="3" enum="Transparency"> diff --git a/doc/classes/Basis.xml b/doc/classes/Basis.xml index f98c207a6e..32077c0b89 100644 --- a/doc/classes/Basis.xml +++ b/doc/classes/Basis.xml @@ -4,10 +4,12 @@ A 3×3 matrix for representing 3D rotation and scale. </brief_description> <description> - A 3×3 matrix used for representing 3D rotation and scale. Usually used as an orthogonal basis for a [Transform3D]. - Contains 3 vector fields X, Y and Z as its columns, which are typically interpreted as the local basis vectors of a transformation. For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S). - Basis can also be accessed as an array of 3D vectors. These vectors are usually orthogonal to each other, but are not necessarily normalized (due to scaling). - For more information, read the "Matrices and transforms" documentation article. + The [Basis] built-in [Variant] type is a 3×3 [url=https://en.wikipedia.org/wiki/Matrix_(mathematics)]matrix[/url] used to represent 3D rotation, scale, and shear. It is frequently used within a [Transform3D]. + A [Basis] is composed by 3 axis vectors, each representing a column of the matrix: [member x], [member y], and [member z]. The length of each axis ([method Vector3.length]) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted. + A [Basis] is [b]orthogonal[/b] if its axes are perpendicular to each other. A basis is [b]normalized[/b] if the length of every axis is [code]1[/code]. A basis is [b]uniform[/b] if all axes share the same length (see [method get_scale]). A basis is [b]orthonormal[/b] if it is both orthogonal and normalized, which allows it to only represent rotations. A basis is [b]conformal[/b] if it is both orthogonal and uniform, which ensures it is not distorted. + For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial. + [b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions]Importing 3D Scenes[/url] tutorial. + [b]Note:[/b] The basis matrices are exposed as [url=https://www.mindcontrol.org/~hplus/graphics/matrix-layout.html]column-major[/url] order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX. </description> <tutorials> <link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link> @@ -22,7 +24,7 @@ <constructor name="Basis"> <return type="Basis" /> <description> - Constructs a default-initialized [Basis] set to [constant IDENTITY]. + Constructs a [Basis] identical to the [constant IDENTITY]. </description> </constructor> <constructor name="Basis"> @@ -37,14 +39,16 @@ <param index="0" name="axis" type="Vector3" /> <param index="1" name="angle" type="float" /> <description> - Constructs a pure rotation basis matrix, rotated around the given [param axis] by [param angle] (in radians). The axis must be a normalized vector. + Constructs a [Basis] that only represents rotation, rotated around the [param axis] by the given [param angle], in radians. The axis must be a normalized vector. + [b]Note:[/b] This is the same as using [method rotated] on the [constant IDENTITY] basis. With more than one angle consider using [method from_euler], instead. </description> </constructor> <constructor name="Basis"> <return type="Basis" /> <param index="0" name="from" type="Quaternion" /> <description> - Constructs a pure rotation basis matrix from the given quaternion. + Constructs a [Basis] that only represents rotation from the given [Quaternion]. + [b]Note:[/b] Quaternions [i]only[/i] store rotation, not scale. Because of this, conversions from [Basis] to [Quaternion] cannot always be reversed. </description> </constructor> <constructor name="Basis"> @@ -53,7 +57,7 @@ <param index="1" name="y_axis" type="Vector3" /> <param index="2" name="z_axis" type="Vector3" /> <description> - Constructs a basis matrix from 3 axis vectors (matrix columns). + Constructs a [Basis] from 3 axis vectors. These are the columns of the basis matrix. </description> </constructor> </constructors> @@ -61,8 +65,10 @@ <method name="determinant" qualifiers="const"> <return type="float" /> <description> - Returns the determinant of the basis matrix. If the basis is uniformly scaled, its determinant is the square of the scale. - A negative determinant means the basis has a negative scale. A zero determinant means the basis isn't invertible, and is usually considered invalid. + Returns the [url=https://en.wikipedia.org/wiki/Determinant]determinant[/url] of this basis's matrix. For advanced math, this number can be used to determine a few attributes: + - If the determinant is exactly [code]0[/code], the basis is not invertible (see [method inverse]). + - If the determinant is a negative number, the basis represents a negative scale. + [b]Note:[/b] If the basis's scale is the same for every axis, its determinant is always that scale by the power of 2. </description> </method> <method name="from_euler" qualifiers="static"> @@ -70,46 +76,114 @@ <param index="0" name="euler" type="Vector3" /> <param index="1" name="order" type="int" default="2" /> <description> - Constructs a pure rotation Basis matrix from Euler angles in the specified Euler rotation order. By default, use YXZ order (most common). See the [enum EulerOrder] enum for possible values. + Constructs a new [Basis] that only represents rotation from the given [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians. + - The [member Vector3.x] should contain the angle around the [member x] axis (pitch). + - The [member Vector3.y] should contain the angle around the [member y] axis (yaw). + - The [member Vector3.z] should contain the angle around the [member z] axis (roll). + [codeblocks] + [gdscript] + # Creates a Basis whose z axis points down. + var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0)) + + print(my_basis.z) # Prints (0, -1, 0). + [/gdscript] + [csharp] + // Creates a Basis whose z axis points down. + var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f)); + + GD.Print(myBasis.Z); // Prints (0, -1, 0). + [/csharp] + [/codeblocks] + The order of each consecutive rotation can be changed with [param order] (see [enum EulerOrder] constants). By default, the YXZ convention is used ([constant EULER_ORDER_YXZ]): the basis rotates first around the Y axis (yaw), then X (pitch), and lastly Z (roll). When using the opposite method [method get_euler], this order is reversed. </description> </method> <method name="from_scale" qualifiers="static"> <return type="Basis" /> <param index="0" name="scale" type="Vector3" /> <description> - Constructs a pure scale basis matrix with no rotation or shearing. The scale values are set as the diagonal of the matrix, and the other parts of the matrix are zero. + Constructs a new [Basis] that only represents scale, with no rotation or shear, from the given [param scale] vector. + [codeblocks] + [gdscript] + var my_basis = Basis.from_scale(Vector3(2, 4, 8)) + + print(my_basis.x) # Prints (2, 0, 0). + print(my_basis.y) # Prints (0, 4, 0). + print(my_basis.z) # Prints (0, 0, 8). + [/gdscript] + [csharp] + var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f)); + + GD.Print(myBasis.X); // Prints (2, 0, 0). + GD.Print(myBasis.Y); // Prints (0, 4, 0). + GD.Print(myBasis.Z); // Prints (0, 0, 8). + [/csharp] + [/codeblocks] + [b]Note:[/b] In linear algebra, the matrix of this basis is also known as a [url=https://en.wikipedia.org/wiki/Diagonal_matrix]diagonal matrix[/url]. </description> </method> <method name="get_euler" qualifiers="const"> <return type="Vector3" /> <param index="0" name="order" type="int" default="2" /> <description> - Returns the basis's rotation in the form of Euler angles. The Euler order depends on the [param order] parameter, by default it uses the YXZ convention: when decomposing, first Z, then X, and Y last. The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle). - Consider using the [method get_rotation_quaternion] method instead, which returns a [Quaternion] quaternion instead of Euler angles. + Returns this basis's rotation as a [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians. + - The [member Vector3.x] contains the angle around the [member x] axis (pitch); + - The [member Vector3.y] contains the angle around the [member y] axis (yaw); + - The [member Vector3.z] contains the angle around the [member z] axis (roll). + The order of each consecutive rotation can be changed with [param order] (see [enum EulerOrder] constants). By default, the YXZ convention is used ([constant EULER_ORDER_YXZ]): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method [method from_euler], this order is reversed. + [b]Note:[/b] Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the [method get_rotation_quaternion] method instead, which returns a [Quaternion]. + [b]Note:[/b] In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the [member Node3D.rotation] property. </description> </method> <method name="get_rotation_quaternion" qualifiers="const"> <return type="Quaternion" /> <description> - Returns the basis's rotation in the form of a quaternion. See [method get_euler] if you need Euler angles, but keep in mind quaternions should generally be preferred to Euler angles. + Returns this basis's rotation as a [Quaternion]. + [b]Note:[/b] Quatenions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the [method get_euler] method, which returns Euler angles. </description> </method> <method name="get_scale" qualifiers="const"> <return type="Vector3" /> <description> - Assuming that the matrix is the combination of a rotation and scaling, return the absolute value of scaling factors along each axis. + Returns the length of each axis of this basis, as a [Vector3]. If the basis is not sheared, this is the scaling factor. It is not affected by rotation. + [codeblocks] + [gdscript] + var my_basis = Basis( + Vector3(2, 0, 0), + Vector3(0, 4, 0), + Vector3(0, 0, 8) + ) + # Rotating the Basis in any way preserves its scale. + my_basis = my_basis.rotated(Vector3.UP, TAU / 2) + my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4) + + print(my_basis.get_scale()) # Prints (2, 4, 8). + [/gdscript] + [csharp] + var myBasis = new Basis( + Vector3(2.0f, 0.0f, 0.0f), + Vector3(0.0f, 4.0f, 0.0f), + Vector3(0.0f, 0.0f, 8.0f) + ); + // Rotating the Basis in any way preserves its scale. + myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f); + myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f); + + GD.Print(myBasis.Scale); // Prints (2, 4, 8). + [/csharp] + [/codeblocks] + [b]Note:[/b] If the value returned by [method determinant] is negative, the scale is also negative. </description> </method> <method name="inverse" qualifiers="const"> <return type="Basis" /> <description> - Returns the inverse of the matrix. + Returns the [url=https://en.wikipedia.org/wiki/Invertible_matrix]inverse of this basis's matrix[/url]. </description> </method> <method name="is_conformal" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the basis is conformal, meaning it preserves angles and distance ratios, and may only be composed of rotation and uniform scale. Returns [code]false[/code] if the basis has non-uniform scale or shear/skew. This can be used to validate if the basis is non-distorted, which is important for physics and other use cases. + Returns [code]true[/code] if this basis is conformal. A conformal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]uniform[/i] (the axes share the same length). This method can be especially useful during physics calculations. </description> </method> <method name="is_equal_approx" qualifiers="const"> @@ -131,15 +205,35 @@ <param index="1" name="up" type="Vector3" default="Vector3(0, 1, 0)" /> <param index="2" name="use_model_front" type="bool" default="false" /> <description> - Creates a Basis with a rotation such that the forward axis (-Z) points towards the [param target] position. - The up axis (+Y) points as close to the [param up] vector as possible while staying perpendicular to the forward axis. The resulting Basis is orthonormalized. The [param target] and [param up] vectors cannot be zero, and cannot be parallel to each other. - If [param use_model_front] is [code]true[/code], the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the [param target] position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right). + Creates a new [Basis] with a rotation such that the forward axis (-Z) points towards the [param target] position. + By default, the -Z axis (camera forward) is treated as forward (implies +X is right). If [param use_model_front] is [code]true[/code], the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the [param target] position. + The up axis (+Y) points as close to the [param up] vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see [method orthonormalized]). The [param target] and [param up] vectors cannot be [constant Vector3.ZERO], and cannot be parallel to each other. </description> </method> <method name="orthonormalized" qualifiers="const"> <return type="Basis" /> <description> - Returns the orthonormalized version of the matrix (useful to call from time to time to avoid rounding error for orthogonal matrices). This performs a Gram-Schmidt orthonormalization on the basis of the matrix. + Returns the orthonormalized version of this basis. An orthonormal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]normalized[/i] (the axes have a length of [code]1[/code]), which also means it can only represent rotation. + It is often useful to call this method to avoid rounding errors on a rotating basis: + [codeblocks] + [gdscript] + # Rotate this Node3D every frame. + func _process(delta): + basis = basis.rotated(Vector3.UP, TAU * delta) + basis = basis.rotated(Vector3.RIGHT, TAU * delta) + + basis = basis.orthonormalized() + [/gdscript] + [csharp] + // Rotate this Node3D every frame. + public override void _Process(double delta) + { + Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta) + .Rotated(Vector3.Right, Mathf.Tau * (float)delta) + .Orthonormalized(); + } + [/csharp] + [/codeblocks] </description> </method> <method name="rotated" qualifiers="const"> @@ -147,76 +241,183 @@ <param index="0" name="axis" type="Vector3" /> <param index="1" name="angle" type="float" /> <description> - Introduce an additional rotation around the given axis by [param angle] (in radians). The axis must be a normalized vector. + Returns this basis rotated around the given [param axis] by [param angle] (in radians). The [param axis] must be a normalized vector (see [method Vector3.normalized]). + Positive values rotate this basis clockwise around the axis, while negative values rotate it counterclockwise. + [codeblocks] + [gdscript] + var my_basis = Basis.IDENTITY + var angle = TAU / 2 + + my_basis = my_basis.rotated(Vector3.UP, angle) # Rotate around the up axis (yaw). + my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotate around the right axis (pitch). + my_basis = my_basis.rotated(Vector3.BACK, angle) # Rotate around the back axis (roll). + [/gdscript] + [csharp] + var myBasis = Basis.Identity; + var angle = Mathf.Tau / 2.0f; + + myBasis = myBasis.Rotated(Vector3.Up, angle); // Rotate around the up axis (yaw). + myBasis = myBasis.Rotated(Vector3.Right, angle); // Rotate around the right axis (pitch). + myBasis = myBasis.Rotated(Vector3.Back, angle); // Rotate around the back axis (roll). + [/csharp] + [/codeblocks] </description> </method> <method name="scaled" qualifiers="const"> <return type="Basis" /> <param index="0" name="scale" type="Vector3" /> <description> - Introduce an additional scaling specified by the given 3D scaling factor. + Returns this basis with each axis's components scaled by the given [param scale]'s components. + The basis matrix's rows are multiplied by [param scale]'s components. This operation is a global scale (relative to the parent). + [codeblocks] + [gdscript] + var my_basis = Basis( + Vector3(1, 1, 1), + Vector3(2, 2, 2), + Vector3(3, 3, 3) + ) + my_basis = my_basis.scaled(Vector3(0, 2, -2)) + + print(my_basis.x) # Prints (0, 2, -2). + print(my_basis.y) # Prints (0, 4, -4). + print(my_basis.z) # Prints (0, 6, -6). + [/gdscript] + [csharp] + var myBasis = new Basis( + new Vector3(1.0f, 1.0f, 1.0f), + new Vector3(2.0f, 2.0f, 2.0f), + new Vector3(3.0f, 3.0f, 3.0f) + ); + myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f)); + + GD.Print(myBasis.X); // Prints (0, 2, -2). + GD.Print(myBasis.Y); // Prints (0, 4, -4). + GD.Print(myBasis.Z); // Prints (0, 6, -6). + [/csharp] + [/codeblocks] </description> </method> - <method name="slerp" qualifiers="const"> + <method name="slerp" qualifiers="const" keywords="interpolate"> <return type="Basis" /> <param index="0" name="to" type="Basis" /> <param index="1" name="weight" type="float" /> <description> - Assuming that the matrix is a proper rotation matrix, slerp performs a spherical-linear interpolation with another rotation matrix. + Performs a spherical-linear interpolation with the [param to] basis, given a [param weight]. Both this basis and [param to] should represent a rotation. + [b]Example:[/b] Smoothly rotate a [Node3D] to the target basis over time, with a [Tween]. + [codeblock] + var start_basis = Basis.IDENTITY + var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2) + + func _ready(): + create_tween().tween_method(interpolate, 0.0, 1.0, 5.0).set_trans(Tween.TRANS_EXPO) + + func interpolate(weight): + basis = start_basis.slerp(target_basis, weight) + [/codeblock] </description> </method> <method name="tdotx" qualifiers="const"> <return type="float" /> <param index="0" name="with" type="Vector3" /> <description> - Transposed dot product with the X axis of the matrix. + Returns the transposed dot product between [param with] and the [member x] axis (see [method transposed]). + This is equivalent to [code]basis.x.dot(vector)[/code]. </description> </method> <method name="tdoty" qualifiers="const"> <return type="float" /> <param index="0" name="with" type="Vector3" /> <description> - Transposed dot product with the Y axis of the matrix. + Returns the transposed dot product between [param with] and the [member y] axis (see [method transposed]). + This is equivalent to [code]basis.y.dot(vector)[/code]. </description> </method> <method name="tdotz" qualifiers="const"> <return type="float" /> <param index="0" name="with" type="Vector3" /> <description> - Transposed dot product with the Z axis of the matrix. + Returns the transposed dot product between [param with] and the [member z] axis (see [method transposed]). + This is equivalent to [code]basis.z.dot(vector)[/code]. </description> </method> <method name="transposed" qualifiers="const"> <return type="Basis" /> <description> - Returns the transposed version of the matrix. + Returns the transposed version of this basis. This turns the basis matrix's columns into rows, and its rows into columns. + [codeblocks] + [gdscript] + var my_basis = Basis( + Vector3(1, 2, 3), + Vector3(4, 5, 6), + Vector3(7, 8, 9) + ) + my_basis = my_basis.transposed() + + print(my_basis.x) # Prints (1, 4, 7). + print(my_basis.y) # Prints (2, 5, 8). + print(my_basis.z) # Prints (3, 6, 9). + [/gdscript] + [csharp] + var myBasis = new Basis( + new Vector3(1.0f, 2.0f, 3.0f), + new Vector3(4.0f, 5.0f, 6.0f), + new Vector3(7.0f, 8.0f, 9.0f) + ); + myBasis = myBasis.Transposed(); + + GD.Print(myBasis.X); // Prints (1, 4, 7). + GD.Print(myBasis.Y); // Prints (2, 5, 8). + GD.Print(myBasis.Z); // Prints (3, 6, 9). + [/csharp] + [/codeblocks] </description> </method> </methods> <members> <member name="x" type="Vector3" setter="" getter="" default="Vector3(1, 0, 0)"> - The basis matrix's X vector (column 0). Equivalent to array index [code]0[/code]. + The basis's X axis, and the column [code]0[/code] of the matrix. + On the identity basis, this vector points right ([constant Vector3.RIGHT]). </member> <member name="y" type="Vector3" setter="" getter="" default="Vector3(0, 1, 0)"> - The basis matrix's Y vector (column 1). Equivalent to array index [code]1[/code]. + The basis's Y axis, and the column [code]1[/code] of the matrix. + On the identity basis, this vector points up ([constant Vector3.UP]). </member> <member name="z" type="Vector3" setter="" getter="" default="Vector3(0, 0, 1)"> - The basis matrix's Z vector (column 2). Equivalent to array index [code]2[/code]. + The basis's Z axis, and the column [code]2[/code] of the matrix. + On the identity basis, this vector points back ([constant Vector3.BACK]). </member> </members> <constants> <constant name="IDENTITY" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)"> - The identity basis, with no rotation or scaling applied. + The identity basis. This is a basis with no rotation, no shear, and its scale being [code]1[/code]. This means that: + - The [member x] points right ([constant Vector3.RIGHT]); + - The [member y] points up ([constant Vector3.UP]); + - The [member z] points back ([constant Vector3.BACK]). + [codeblock] + var basis := Basis.IDENTITY + print("| X | Y | Z") + print("| %s | %s | %s" % [basis.x.x, basis.y.x, basis.z.x]) + print("| %s | %s | %s" % [basis.x.y, basis.y.y, basis.z.y]) + print("| %s | %s | %s" % [basis.x.z, basis.y.z, basis.z.z]) + # Prints: + # | X | Y | Z + # | 1 | 0 | 0 + # | 0 | 1 | 0 + # | 0 | 0 | 1 + [/codeblock] This is identical to creating [constructor Basis] without any parameters. This constant can be used to make your code clearer, and for consistency with C#. </constant> <constant name="FLIP_X" value="Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)"> - The basis that will flip something along the X axis when used in a transformation. + When any basis is multiplied by [constant FLIP_X], it negates all components of the [member x] axis (the X column). + When [constant FLIP_X] is multiplied by any basis, it negates the [member Vector3.x] component of all axes (the X row). </constant> <constant name="FLIP_Y" value="Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)"> - The basis that will flip something along the Y axis when used in a transformation. + When any basis is multiplied by [constant FLIP_Y], it negates all components of the [member y] axis (the Y column). + When [constant FLIP_Y] is multiplied by any basis, it negates the [member Vector3.y] component of all axes (the Y row). </constant> <constant name="FLIP_Z" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)"> - The basis that will flip something along the Z axis when used in a transformation. + When any basis is multiplied by [constant FLIP_Z], it negates all components of the [member z] axis (the Z column). + When [constant FLIP_Z] is multiplied by any basis, it negates the [member Vector3.z] component of all axes (the Z row). </constant> </constants> <operators> @@ -224,7 +425,7 @@ <return type="bool" /> <param index="0" name="right" type="Basis" /> <description> - Returns [code]true[/code] if the [Basis] matrices are not equal. + Returns [code]true[/code] if the components of both [Basis] matrices are not equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -232,35 +433,60 @@ <return type="Basis" /> <param index="0" name="right" type="Basis" /> <description> - Composes these two basis matrices by multiplying them together. This has the effect of transforming the second basis (the child) by the first basis (the parent). + Transforms (multiplies) the [param right] basis by this basis. + This is the operation performed between parent and child [Node3D]s. </description> </operator> <operator name="operator *"> <return type="Vector3" /> <param index="0" name="right" type="Vector3" /> <description> - Transforms (multiplies) the [Vector3] by the given [Basis] matrix. + Transforms (multiplies) the [param right] vector by this basis, returning a [Vector3]. + [codeblocks] + [gdscript] + var my_basis = Basis(Vector3(1, 1, 1), Vector3(1, 1, 1), Vector3(0, 2, 5)) + print(my_basis * Vector3(1, 2, 3)) # Prints (7, 3, 16) + [/gdscript] + [csharp] + var myBasis = new Basis(new Vector3(1, 1, 1), new Vector3(1, 1, 1), new Vector3(0, 2, 5)); + GD.Print(my_basis * new Vector3(1, 2, 3)); // Prints (7, 3, 16) + [/csharp] + [/codeblocks] </description> </operator> <operator name="operator *"> <return type="Basis" /> <param index="0" name="right" type="float" /> <description> - This operator multiplies all components of the [Basis], which scales it uniformly. + Multiplies all components of the [Basis] by the given [float]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value. </description> </operator> <operator name="operator *"> <return type="Basis" /> <param index="0" name="right" type="int" /> <description> - This operator multiplies all components of the [Basis], which scales it uniformly. + Multiplies all components of the [Basis] by the given [int]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value. + </description> + </operator> + <operator name="operator /"> + <return type="Basis" /> + <param index="0" name="right" type="float" /> + <description> + Divides all components of the [Basis] by the given [float]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value. + </description> + </operator> + <operator name="operator /"> + <return type="Basis" /> + <param index="0" name="right" type="int" /> + <description> + Divides all components of the [Basis] by the given [int]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="Basis" /> <description> - Returns [code]true[/code] if the [Basis] matrices are exactly equal. + Returns [code]true[/code] if the components of both [Basis] matrices are exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -268,7 +494,8 @@ <return type="Vector3" /> <param index="0" name="index" type="int" /> <description> - Access basis components using their index. [code]b[0][/code] is equivalent to [code]b.x[/code], [code]b[1][/code] is equivalent to [code]b.y[/code], and [code]b[2][/code] is equivalent to [code]b.z[/code]. + Accesses each axis (column) of this basis by their index. Index [code]0[/code] is the same as [member x], index [code]1[/code] is the same as [member y], and index [code]2[/code] is the same as [member z]. + [b]Note:[/b] In C++, this operator accesses the rows of the basis matrix, [i]not[/i] the columns. For the same behavior as scripting languages, use the [code]set_column[/code] and [code]get_column[/code] methods. </description> </operator> </operators> diff --git a/doc/classes/Bone2D.xml b/doc/classes/Bone2D.xml index a62c160080..da7f08e53d 100644 --- a/doc/classes/Bone2D.xml +++ b/doc/classes/Bone2D.xml @@ -15,7 +15,7 @@ <method name="apply_rest"> <return type="void" /> <description> - Stores the node's current transforms in [member rest]. + Resets the bone to the rest pose. This is equivalent to setting [member Node2D.transform] to [member rest]. </description> </method> <method name="get_autocalculate_length_and_angle" qualifiers="const"> diff --git a/doc/classes/BoneAttachment3D.xml b/doc/classes/BoneAttachment3D.xml index 111e58e981..bafa463f82 100644 --- a/doc/classes/BoneAttachment3D.xml +++ b/doc/classes/BoneAttachment3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="BoneAttachment3D" inherits="Node3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="BoneAttachment3D" inherits="Node3D" keywords="tag" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> А node that dynamically copies or overrides the 3D transform of a bone in its parent [Skeleton3D]. </brief_description> @@ -52,6 +52,7 @@ </member> <member name="override_pose" type="bool" setter="set_override_pose" getter="get_override_pose" default="false"> Whether the BoneAttachment3D node will override the bone pose of the bone it is attached to. When set to [code]true[/code], the BoneAttachment3D node can change the pose of the bone. When set to [code]false[/code], the BoneAttachment3D will always be set to the bone's transform. + [b]Note:[/b] 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]. </member> </members> </class> diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index d7782a816d..e5b47ffb89 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -43,6 +43,9 @@ <member name="alignment" type="int" setter="set_text_alignment" getter="get_text_alignment" enum="HorizontalAlignment" default="1"> Text alignment policy for the button's text, use one of the [enum HorizontalAlignment] constants. </member> + <member name="autowrap_mode" type="int" setter="set_autowrap_mode" getter="get_autowrap_mode" enum="TextServer.AutowrapMode" default="0"> + If set to something other than [constant TextServer.AUTOWRAP_OFF], the text gets wrapped inside the node's bounding rectangle. + </member> <member name="clip_text" type="bool" setter="set_clip_text" getter="get_clip_text" default="false"> When this property is enabled, text that is too large to fit the button is clipped, when disabled the Button will always be wide enough to hold the text. </member> @@ -91,7 +94,7 @@ <theme_item name="font_hover_pressed_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> Text [Color] used when the [Button] is being hovered and pressed. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the [Button]. </theme_item> <theme_item name="font_pressed_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> @@ -134,7 +137,7 @@ <theme_item name="icon" data_type="icon" type="Texture2D"> Default icon for the [Button]. Appears only if [member icon] is not assigned. </theme_item> - <theme_item name="disabled" data_type="style" type="StyleBox"> + <theme_item name="disabled" data_type="style" type="StyleBox" keywords="enabled"> [StyleBox] used when the [Button] is disabled. </theme_item> <theme_item name="disabled_mirrored" data_type="style" type="StyleBox"> diff --git a/doc/classes/CPUParticles2D.xml b/doc/classes/CPUParticles2D.xml index 92a57007bd..99411c73aa 100644 --- a/doc/classes/CPUParticles2D.xml +++ b/doc/classes/CPUParticles2D.xml @@ -126,7 +126,7 @@ <member name="anim_speed_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0"> Minimum equivalent of [member anim_speed_max]. </member> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour"> Each particle's initial color. If [member texture] is defined, it will be multiplied by this color. </member> <member name="color_initial_ramp" type="Gradient" setter="set_color_initial_ramp" getter="get_color_initial_ramp"> diff --git a/doc/classes/CPUParticles3D.xml b/doc/classes/CPUParticles3D.xml index 27404b68bb..27726ff8a2 100644 --- a/doc/classes/CPUParticles3D.xml +++ b/doc/classes/CPUParticles3D.xml @@ -125,7 +125,7 @@ <member name="anim_speed_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0"> Minimum particle animation speed. </member> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour"> Each particle's initial color. [b]Note:[/b] [member color] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color] will have no visible effect. </member> @@ -309,6 +309,10 @@ <member name="tangential_accel_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0"> Minimum tangent acceleration. </member> + <member name="visibility_aabb" type="AABB" setter="set_visibility_aabb" getter="get_visibility_aabb" default="AABB(0, 0, 0, 0, 0, 0)"> + The [AABB] that determines the node's region which needs to be visible on screen for the particle system to be active. + Grow the box if particles suddenly appear/disappear when the node enters/exits the screen. The [AABB] can be grown via code or with the [b]Particles → Generate AABB[/b] editor tool. + </member> </members> <signals> <signal name="finished"> diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml index b903e98319..05174abb07 100644 --- a/doc/classes/Callable.xml +++ b/doc/classes/Callable.xml @@ -4,7 +4,7 @@ A built-in type representing a method or a standalone function. </brief_description> <description> - [Callable] is a built-in [Variant] type that represents a function. It can either be a method within an [Object] instance, or a standalone function not related to any object, like a lambda function. Like all [Variant] types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. + [Callable] is a built-in [Variant] type that represents a function. It can either be a method within an [Object] instance, or a custom callable used for different purposes (see [method is_custom]). Like all [Variant] types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. [b]Example:[/b] [codeblocks] [gdscript] @@ -46,16 +46,21 @@ # Prints "Attack!", when the button_pressed signal is emitted. button_pressed.connect(func(): print("Attack!")) [/codeblock] - [b]Note:[/b] Methods of native types such as [Signal], [Array], or [Dictionary] are not of type [Callable] in order to avoid unnecessary overhead. If you need to pass those methods as [Callable], use a lambda function as a wrapper. + In GDScript, you can access methods and global functions as [Callable]s: [codeblock] - func _init(): - var my_dictionary = { "hello": "world" } + 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. + [/codeblock] + [b]Note:[/b] [Dictionary] does not support the above due to ambiguity with keys. + [codeblock] + var dictionary = {"hello": "world"} - # This will not work, `clear` is not a callable. - create_tween().tween_callback(my_dictionary.clear) + # This will not work, `clear` is treated as a key. + tween.tween_callback(dictionary.clear) - # This will work, as lambdas are custom callables. - create_tween().tween_callback(func(): my_dictionary.clear()) + # This will work. + tween.tween_callback(Callable.create(dictionary, "clear")) [/codeblock] </description> <tutorials> @@ -80,6 +85,7 @@ <param index="1" name="method" type="StringName" /> <description> Creates a new [Callable] for the method named [param method] in the specified [param object]. + [b]Note:[/b] For methods of built-in [Variant] types, use [method create] instead. </description> </constructor> </constructors> @@ -109,10 +115,19 @@ <return type="void" /> <description> 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. - [codeblock] + [codeblocks] + [gdscript] func _ready(): grab_focus.call_deferred() - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + Callable.From(GrabFocus).CallDeferred(); + } + [/csharp] + [/codeblocks] + [b]Note:[/b] 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 [method Object.call_deferred]. </description> </method> @@ -123,6 +138,21 @@ Calls the method represented by this [Callable]. Unlike [method call], this method expects all arguments to be contained inside the [param arguments] [Array]. </description> </method> + <method name="create" qualifiers="static"> + <return type="Callable" /> + <param index="0" name="variant" type="Variant" /> + <param index="1" name="method" type="StringName" /> + <description> + Creates a new [Callable] for the method named [param method] in the specified [param variant]. To represent a method of a built-in [Variant] type, a custom callable is used (see [method is_custom]). If [param variant] is [Object], then a standard callable will be created instead. + [b]Note:[/b] This method is always necessary for the [Dictionary] type, as property syntax is used to access its entries. You may also use this method when [param variant]'s type is not known in advance (for polymorphism). + </description> + </method> + <method name="get_argument_count" qualifiers="const"> + <return type="int" /> + <description> + Returns the total number of arguments this [Callable] should take, including optional arguments. This means that any arguments bound with [method bind] are [i]subtracted[/i] from the result, and any arguments unbound with [method unbind] are [i]added[/i] to the result. + </description> + </method> <method name="get_bound_arguments" qualifiers="const"> <return type="Array" /> <description> @@ -163,7 +193,11 @@ <method name="is_custom" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this [Callable] is a custom callable. Custom callables are created from [method bind] or [method unbind]. In GDScript, lambda functions are also custom callables. + Returns [code]true[/code] if this [Callable] is a custom callable. Custom callables are used: + - for binding/unbinding arguments (see [method bind] and [method unbind]); + - for representing methods of built-in [Variant] types (see [method create]); + - for representing global, lambda, and RPC functions in GDScript; + - for other purposes in the core, GDExtension, and C#. </description> </method> <method name="is_null" qualifiers="const"> diff --git a/doc/classes/Camera3D.xml b/doc/classes/Camera3D.xml index 07b23e0252..01890b471c 100644 --- a/doc/classes/Camera3D.xml +++ b/doc/classes/Camera3D.xml @@ -159,6 +159,9 @@ <member name="attributes" type="CameraAttributes" setter="set_attributes" getter="get_attributes"> The [CameraAttributes] to use for this camera. </member> + <member name="compositor" type="Compositor" setter="set_compositor" getter="get_compositor"> + The [Compositor] to use for this camera. + </member> <member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="1048575"> The culling mask that describes which [member VisualInstance3D.layers] are rendered by this camera. By default, all 20 user-visible layers are rendered. [b]Note:[/b] Since the [member 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 [member cull_mask] using a script allows you to toggle those reserved layers, which can be useful for editor plugins. diff --git a/doc/classes/CameraAttributesPhysical.xml b/doc/classes/CameraAttributesPhysical.xml index 69af64b7ff..faedfee712 100644 --- a/doc/classes/CameraAttributesPhysical.xml +++ b/doc/classes/CameraAttributesPhysical.xml @@ -32,7 +32,7 @@ Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. </member> <member name="exposure_shutter_speed" type="float" setter="set_shutter_speed" getter="get_shutter_speed" default="100.0"> - Time for shutter to open and close, measured in seconds. A higher value will let in more light leading to a brighter image, while a lower amount will let in less light leading to a darker image. + Time for shutter to open and close, evaluated as [code]1 / shutter_speed[/code] seconds. A higher value will allow less light (leading to a darker image), while a lower value will allow more light (leading to a brighter image). Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. </member> <member name="frustum_far" type="float" setter="set_far" getter="get_far" default="4000.0"> diff --git a/doc/classes/CameraAttributesPractical.xml b/doc/classes/CameraAttributesPractical.xml index 8a5956cc87..893bc27f91 100644 --- a/doc/classes/CameraAttributesPractical.xml +++ b/doc/classes/CameraAttributesPractical.xml @@ -17,7 +17,7 @@ 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. </member> <member name="dof_blur_amount" type="float" setter="set_dof_blur_amount" getter="get_dof_blur_amount" default="0.1"> - 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 bluriness, but can be much more expensive to calculate. It is best to keep this as low as possible for a given art style. + 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. </member> <member name="dof_blur_far_distance" type="float" setter="set_dof_blur_far_distance" getter="get_dof_blur_far_distance" default="10.0"> Objects further from the [Camera3D] by this amount will be blurred by the depth of field effect. Measured in meters. diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 5a2df0e8a4..72783bc5d6 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -411,6 +411,12 @@ Returns the canvas item RID used by [RenderingServer] for this item. </description> </method> + <method name="get_canvas_layer_node" qualifiers="const"> + <return type="CanvasLayer" /> + <description> + Returns the [CanvasLayer] that contains this node, or [code]null[/code] if the node is not in any [CanvasLayer]. + </description> + </method> <method name="get_canvas_transform" qualifiers="const"> <return type="Transform2D" /> <description> @@ -501,7 +507,7 @@ <method name="is_visible_in_tree" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is consequently not drawn (see [method _draw]). + Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see [method _draw]). </description> </method> <method name="make_canvas_position_local" qualifiers="const"> @@ -522,7 +528,7 @@ <return type="void" /> <description> Moves this node to display on top of its siblings. - Internally, the node is moved to the bottom of parent's children list. The method has no effect on nodes without a parent. + Internally, the node is moved to the bottom of parent's child list. The method has no effect on nodes without a parent. </description> </method> <method name="queue_redraw"> @@ -562,7 +568,7 @@ </methods> <members> <member name="clip_children" type="int" setter="set_clip_children_mode" getter="get_clip_children_mode" enum="CanvasItem.ClipChildrenMode" default="0"> - Allows the current node to clip children nodes, essentially acting as a mask. + Allows the current node to clip child nodes, essentially acting as a mask. </member> <member name="light_mask" type="int" setter="set_light_mask" getter="get_light_mask" default="1"> The rendering layers in which this [CanvasItem] responds to [Light2D] nodes. @@ -570,7 +576,7 @@ <member name="material" type="Material" setter="set_material" getter="get_material"> The material applied to this [CanvasItem]. </member> - <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)"> + <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)" keywords="color, colour"> The color applied to this [CanvasItem]. This property does affect child [CanvasItem]s, unlike [member self_modulate] which only affects the node itself. </member> <member name="self_modulate" type="Color" setter="set_self_modulate" getter="get_self_modulate" default="Color(1, 1, 1, 1)"> @@ -600,7 +606,7 @@ [b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead. </member> <member name="y_sort_enabled" type="bool" setter="set_y_sort_enabled" getter="is_y_sort_enabled" default="false"> - If [code]true[/code], child nodes with the lowest Y position are drawn before those with a higher Y position. If [code]false[/code], Y-sorting is disabled. Y-sorting only affects children that inherit from [CanvasItem]. + If [code]true[/code], this [CanvasItem] and its [CanvasItem] child nodes are sorted according to the Y position. Nodes with a lower Y position are drawn before those with a higher Y position. If [code]false[/code], Y-sorting is disabled. You can nest nodes with Y-sorting. Child Y-sorted nodes are sorted in the same space as the parent Y-sort. This feature allows you to organize a scene better or divide it into multiple ones without changing your scene tree. </member> <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" default="true"> @@ -660,24 +666,26 @@ The [CanvasItem] will inherit the filter from its parent. </constant> <constant name="TEXTURE_FILTER_NEAREST" value="1" enum="TextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering. Useful for pixel art. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_LINEAR" value="2" enum="TextureFilter"> - The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="3" enum="TextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. This is the fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="4" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC" value="5" enum="TextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_NEAREST_WITH_MIPMAPS] is usually more appropriate. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_NEAREST_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC" value="6" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_LINEAR_WITH_MIPMAPS] is usually more appropriate. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_LINEAR_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="TEXTURE_FILTER_MAX" value="7" enum="TextureFilter"> Represents the size of the [enum TextureFilter] enum. @@ -692,7 +700,7 @@ Texture will repeat normally. </constant> <constant name="TEXTURE_REPEAT_MIRROR" value="3" enum="TextureRepeat"> - Texture will repeat in a 2x2 tiled mode, where elements at even positions are mirrored. + Texture will repeat in a 2×2 tiled mode, where elements at even positions are mirrored. </constant> <constant name="TEXTURE_REPEAT_MAX" value="4" enum="TextureRepeat"> Represents the size of the [enum TextureRepeat] enum. diff --git a/doc/classes/CanvasModulate.xml b/doc/classes/CanvasModulate.xml index 214b3959c7..7db0361020 100644 --- a/doc/classes/CanvasModulate.xml +++ b/doc/classes/CanvasModulate.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="CanvasModulate" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="CanvasModulate" inherits="Node2D" keywords="color" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A node that applies a color tint to a canvas. </brief_description> @@ -9,7 +9,7 @@ <tutorials> </tutorials> <members> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour"> The tint color to apply. </member> </members> diff --git a/doc/classes/CanvasTexture.xml b/doc/classes/CanvasTexture.xml index 1b22adb723..a14f71cc46 100644 --- a/doc/classes/CanvasTexture.xml +++ b/doc/classes/CanvasTexture.xml @@ -5,7 +5,7 @@ </brief_description> <description> [CanvasTexture] is an alternative to [ImageTexture] for 2D rendering. It allows using normal maps and specular maps in any node that inherits from [CanvasItem]. [CanvasTexture] also allows overriding the texture's filter and repeat mode independently of the node's properties (or the project settings). - [b]Note:[/b] [CanvasTexture] cannot be used in 3D rendering. For physically-based materials in 3D, use [BaseMaterial3D] instead. + [b]Note:[/b] [CanvasTexture] cannot be used in 3D. It will not display correctly when applied to any [VisualInstance3D], such as [Sprite3D] or [Decal]. For physically-based materials in 3D, use [BaseMaterial3D] instead. </description> <tutorials> <link title="2D Lights and Shadows">$DOCS_URL/tutorials/2d/2d_lights_and_shadows.html</link> diff --git a/doc/classes/CharFXTransform.xml b/doc/classes/CharFXTransform.xml index ce74227298..403033f85d 100644 --- a/doc/classes/CharFXTransform.xml +++ b/doc/classes/CharFXTransform.xml @@ -11,7 +11,7 @@ <link title="RichTextEffect test project (third-party)">https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project</link> </tutorials> <members> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)" keywords="colour"> The color the character will be drawn with. </member> <member name="elapsed_time" type="float" setter="set_elapsed_time" getter="get_elapsed_time" default="0.0"> diff --git a/doc/classes/ClassDB.xml b/doc/classes/ClassDB.xml index d24181c3d3..3f71406091 100644 --- a/doc/classes/ClassDB.xml +++ b/doc/classes/ClassDB.xml @@ -65,6 +65,15 @@ Returns an array with the names all the integer constants of [param class] or its ancestry. </description> </method> + <method name="class_get_method_argument_count" qualifiers="const"> + <return type="int" /> + <param index="0" name="class" type="StringName" /> + <param index="1" name="method" type="StringName" /> + <param index="2" name="no_inheritance" type="bool" default="false" /> + <description> + Returns the number of arguments of the method [param method] of [param class] or its ancestry if [param no_inheritance] is [code]false[/code]. + </description> + </method> <method name="class_get_method_list" qualifiers="const"> <return type="Dictionary[]" /> <param index="0" name="class" type="StringName" /> diff --git a/doc/classes/CodeEdit.xml b/doc/classes/CodeEdit.xml index 13f39d4fae..7c6f1a51c4 100644 --- a/doc/classes/CodeEdit.xml +++ b/doc/classes/CodeEdit.xml @@ -48,7 +48,7 @@ <param index="2" name="insert_text" type="String" /> <param index="3" name="text_color" type="Color" default="Color(1, 1, 1, 1)" /> <param index="4" name="icon" type="Resource" default="null" /> - <param index="5" name="value" type="Variant" default="0" /> + <param index="5" name="value" type="Variant" default="null" /> <param index="6" name="location" type="int" default="1024" /> <description> Submits an item to the queue of potential candidates for the autocomplete menu. Call [method update_code_completion_options] to update the list. @@ -62,9 +62,8 @@ <param index="1" name="end_key" type="String" /> <param index="2" name="line_only" type="bool" default="false" /> <description> - Adds a comment delimiter. - Both the start and end keys must be symbols. Only the start key has to be unique. - [param line_only] denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. + Adds a comment delimiter from [param start_key] to [param end_key]. Both keys should be symbols, and [param start_key] must not be shared with other delimiters. + If [param line_only] is [code]true[/code] or [param end_key] is an empty [String], the region does not carry over to the next line. </description> </method> <method name="add_string_delimiter"> @@ -73,9 +72,8 @@ <param index="1" name="end_key" type="String" /> <param index="2" name="line_only" type="bool" default="false" /> <description> - Adds a string delimiter. - Both the start and end keys must be symbols. Only the start key has to be unique. - [param line_only] denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. + Defines a string delimiter from [param start_key] to [param end_key]. Both keys should be symbols, and [param start_key] must not be shared with other delimiters. + If [param line_only] is [code]true[/code] or [param end_key] is an empty [String], the region does not carry over to the next line. </description> </method> <method name="can_fold_line" qualifiers="const"> @@ -623,7 +621,7 @@ 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). </constant> <constant name="LOCATION_PARENT_MASK" value="256" enum="CodeCompletionLocation"> - 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. + 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. [code]0[/code] for the local class, [code]1[/code] for the parent, [code]2[/code] for the grandparent, etc.) to store the depth of an option in the class or a parent class. </constant> <constant name="LOCATION_OTHER_USER_CODE" value="512" enum="CodeCompletionLocation"> The option is from user code which is not local and not in a derived class (e.g. Autoload Singletons). diff --git a/doc/classes/CodeHighlighter.xml b/doc/classes/CodeHighlighter.xml index 3005ffcdca..ca2caf6be5 100644 --- a/doc/classes/CodeHighlighter.xml +++ b/doc/classes/CodeHighlighter.xml @@ -16,9 +16,8 @@ <param index="2" name="color" type="Color" /> <param index="3" name="line_only" type="bool" default="false" /> <description> - Adds a color region such as comments or strings. - Both the start and end keys must be symbols. Only the start key has to be unique. - [param line_only] denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. + Adds a color region (such as for comments or strings) from [param start_key] to [param end_key]. Both keys should be symbols, and [param start_key] must not be shared with other delimiters. + If [param line_only] is [code]true[/code] or [param end_key] is an empty [String], the region does not carry over to the next line. </description> </method> <method name="add_keyword_color"> diff --git a/doc/classes/CollisionObject3D.xml b/doc/classes/CollisionObject3D.xml index b45a5d8c56..063c27c76a 100644 --- a/doc/classes/CollisionObject3D.xml +++ b/doc/classes/CollisionObject3D.xml @@ -14,11 +14,11 @@ <return type="void" /> <param index="0" name="camera" type="Camera3D" /> <param index="1" name="event" type="InputEvent" /> - <param index="2" name="position" type="Vector3" /> + <param index="2" name="event_position" type="Vector3" /> <param index="3" name="normal" type="Vector3" /> <param index="4" name="shape_idx" type="int" /> <description> - Receives unhandled [InputEvent]s. [param position] is the location in world space of the mouse pointer on the surface of the shape with index [param shape_idx] and [param normal] is the normal vector of the surface at that point. Connect to the [signal input_event] signal to easily pick up these events. + Receives unhandled [InputEvent]s. [param event_position] is the location in world space of the mouse pointer on the surface of the shape with index [param shape_idx] and [param normal] is the normal vector of the surface at that point. Connect to the [signal input_event] signal to easily pick up these events. [b]Note:[/b] [method _input_event] requires [member input_ray_pickable] to be [code]true[/code] and at least one [member collision_layer] bit to be set. </description> </method> @@ -207,11 +207,11 @@ <signal name="input_event"> <param index="0" name="camera" type="Node" /> <param index="1" name="event" type="InputEvent" /> - <param index="2" name="position" type="Vector3" /> + <param index="2" name="event_position" type="Vector3" /> <param index="3" name="normal" type="Vector3" /> <param index="4" name="shape_idx" type="int" /> <description> - Emitted when the object receives an unhandled [InputEvent]. [param position] is the location in world space of the mouse pointer on the surface of the shape with index [param shape_idx] and [param normal] is the normal vector of the surface at that point. + Emitted when the object receives an unhandled [InputEvent]. [param event_position] is the location in world space of the mouse pointer on the surface of the shape with index [param shape_idx] and [param normal] is the normal vector of the surface at that point. </description> </signal> <signal name="mouse_entered"> diff --git a/doc/classes/CollisionPolygon2D.xml b/doc/classes/CollisionPolygon2D.xml index d6f3b7cb5d..29535ffd64 100644 --- a/doc/classes/CollisionPolygon2D.xml +++ b/doc/classes/CollisionPolygon2D.xml @@ -4,7 +4,7 @@ A node that provides a polygon shape to a [CollisionObject2D] parent. </brief_description> <description> - A node that provides a thickened polygon shape (a prism) to a [CollisionObject2D] parent and allows to edit it. The polygon can be concave or convex. This can give a detection shape to an [Area2D] or turn [PhysicsBody2D] into a solid object. + A node that provides a polygon shape to a [CollisionObject2D] parent and allows to edit it. The polygon can be concave or convex. This can give a detection shape to an [Area2D], turn [PhysicsBody2D] into a solid object, or give a hollow shape to a [StaticBody2D]. [b]Warning:[/b] A non-uniformly scaled [CollisionShape2D] will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its shape resource instead. </description> <tutorials> @@ -13,7 +13,7 @@ <member name="build_mode" type="int" setter="set_build_mode" getter="get_build_mode" enum="CollisionPolygon2D.BuildMode" default="0"> Collision build mode. Use one of the [enum BuildMode] constants. </member> - <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false"> + <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled"> If [code]true[/code], no collisions will be detected. </member> <member name="one_way_collision" type="bool" setter="set_one_way_collision" getter="is_one_way_collision_enabled" default="false"> @@ -25,6 +25,7 @@ </member> <member name="polygon" type="PackedVector2Array" setter="set_polygon" getter="get_polygon" default="PackedVector2Array()"> The polygon's list of vertices. Each point will be connected to the next, and the final point will be connected to the first. + [b]Note:[/b] The returned vertices are in the local coordinate space of the given [CollisionPolygon2D]. [b]Warning:[/b] The returned value is a clone of the [PackedVector2Array], not a reference. </member> </members> diff --git a/doc/classes/CollisionPolygon3D.xml b/doc/classes/CollisionPolygon3D.xml index ed6fa0ba3c..16090c203e 100644 --- a/doc/classes/CollisionPolygon3D.xml +++ b/doc/classes/CollisionPolygon3D.xml @@ -13,7 +13,7 @@ <member name="depth" type="float" setter="set_depth" getter="get_depth" default="1.0"> Length that the resulting collision extends in either direction perpendicular to its 2D polygon. </member> - <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false"> + <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled"> If [code]true[/code], no collision will be produced. </member> <member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.04"> diff --git a/doc/classes/CollisionShape2D.xml b/doc/classes/CollisionShape2D.xml index f3143e1f5c..1320982376 100644 --- a/doc/classes/CollisionShape2D.xml +++ b/doc/classes/CollisionShape2D.xml @@ -17,7 +17,7 @@ The collision shape debug color. [b]Note:[/b] The default value is [member ProjectSettings.debug/shapes/collision/shape_color]. The [code]Color(0, 0, 0, 1)[/code] value documented here is a placeholder, and not the actual default debug color. </member> - <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false"> + <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled"> A disabled collision shape has no effect in the world. This property should be changed with [method Object.set_deferred]. </member> <member name="one_way_collision" type="bool" setter="set_one_way_collision" getter="is_one_way_collision_enabled" default="false"> diff --git a/doc/classes/CollisionShape3D.xml b/doc/classes/CollisionShape3D.xml index 4e32545f27..f6c0c323f4 100644 --- a/doc/classes/CollisionShape3D.xml +++ b/doc/classes/CollisionShape3D.xml @@ -20,16 +20,16 @@ Sets the collision shape's shape to the addition of all its convexed [MeshInstance3D] siblings geometry. </description> </method> - <method name="resource_changed" is_deprecated="true"> + <method name="resource_changed" deprecated="Use [signal Resource.changed] instead."> <return type="void" /> <param index="0" name="resource" type="Resource" /> <description> - [i]Obsoleted.[/i] Use [signal Resource.changed] instead. + This method does nothing. </description> </method> </methods> <members> - <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false"> + <member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled"> A disabled collision shape has no effect in the world. </member> <member name="shape" type="Shape3D" setter="set_shape" getter="get_shape"> diff --git a/doc/classes/Color.xml b/doc/classes/Color.xml index 86e421b5b8..942d3bc80d 100644 --- a/doc/classes/Color.xml +++ b/doc/classes/Color.xml @@ -4,7 +4,7 @@ A color represented in RGBA format. </brief_description> <description> - A color represented in RGBA format by a red ([member r]), green ([member g]), blue ([member b]), and alpha ([member a]) component. Each component is a 16-bit floating-point value, usually ranging from [code]0.0[/code] to [code]1.0[/code]. Some properties (such as [member CanvasItem.modulate]) may support values greater than [code]1.0[/code], for overbright or HDR (High Dynamic Range) colors. + A color represented in RGBA format by a red ([member r]), green ([member g]), blue ([member b]), and alpha ([member a]) component. Each component is a 32-bit floating-point value, usually ranging from [code]0.0[/code] to [code]1.0[/code]. Some properties (such as [member CanvasItem.modulate]) may support values greater than [code]1.0[/code], 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 [method from_hsv], and by using a name from the set of standardized colors based on [url=https://en.wikipedia.org/wiki/X11_color_names]X11 color names[/url] with the addition of [constant TRANSPARENT]. GDScript also provides [method @GDScript.Color8], which uses integers from [code]0[/code] to [code]255[/code] and doesn't support overbright colors. [b]Note:[/b] In a boolean context, a Color will evaluate to [code]false[/code] if it is equal to [code]Color(0, 0, 0, 1)[/code] (opaque black). Otherwise, a Color will always evaluate to [code]true[/code]. [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/color_constants.png]Color constants cheatsheet[/url] @@ -181,7 +181,7 @@ <return type="Color" /> <param index="0" name="rgbe" type="int" /> <description> - Decodes a [Color] from a RGBE9995 format integer. See [constant Image.FORMAT_RGBE9995]. + Decodes a [Color] from an RGBE9995 format integer. See [constant Image.FORMAT_RGBE9995]. </description> </method> <method name="from_string" qualifiers="static"> @@ -299,7 +299,7 @@ Returns [code]true[/code] if this color and [param to] are approximately equal, by running [method @GlobalScope.is_equal_approx] on each component. </description> </method> - <method name="lerp" qualifiers="const"> + <method name="lerp" qualifiers="const" keywords="interpolate"> <return type="Color" /> <param index="0" name="to" type="Color" /> <param index="1" name="weight" type="float" /> diff --git a/doc/classes/ColorPicker.xml b/doc/classes/ColorPicker.xml index dfa8d7d840..9aa0122ed2 100644 --- a/doc/classes/ColorPicker.xml +++ b/doc/classes/ColorPicker.xml @@ -58,7 +58,7 @@ <member name="can_add_swatches" type="bool" setter="set_can_add_swatches" getter="are_swatches_enabled" default="true"> If [code]true[/code], it's possible to add presets under Swatches. If [code]false[/code], the button to add presets is disabled. </member> - <member name="color" type="Color" setter="set_pick_color" getter="get_pick_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_pick_color" getter="get_pick_color" default="Color(1, 1, 1, 1)" keywords="colour"> The currently selected color. </member> <member name="color_mode" type="int" setter="set_color_mode" getter="get_color_mode" enum="ColorPicker.ColorModeType" default="0"> @@ -186,6 +186,9 @@ <theme_item name="sample_bg" data_type="icon" type="Texture2D"> Background panel for the color preview box (visible when the color is translucent). </theme_item> + <theme_item name="sample_revert" data_type="icon" type="Texture2D"> + 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. + </theme_item> <theme_item name="screen_picker" data_type="icon" type="Texture2D"> The icon for the screen color picker button. </theme_item> diff --git a/doc/classes/ColorPickerButton.xml b/doc/classes/ColorPickerButton.xml index 89cb01407d..c53d61f036 100644 --- a/doc/classes/ColorPickerButton.xml +++ b/doc/classes/ColorPickerButton.xml @@ -29,7 +29,7 @@ </method> </methods> <members> - <member name="color" type="Color" setter="set_pick_color" getter="get_pick_color" default="Color(0, 0, 0, 1)"> + <member name="color" type="Color" setter="set_pick_color" getter="get_pick_color" default="Color(0, 0, 0, 1)" keywords="colour"> The currently selected color. </member> <member name="edit_alpha" type="bool" setter="set_edit_alpha" getter="is_editing_alpha" default="true"> diff --git a/doc/classes/ColorRect.xml b/doc/classes/ColorRect.xml index 5bc97e6f46..413d51db72 100644 --- a/doc/classes/ColorRect.xml +++ b/doc/classes/ColorRect.xml @@ -10,7 +10,7 @@ <link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/515</link> </tutorials> <members> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour"> The fill color of the rectangle. </member> </members> diff --git a/doc/classes/Compositor.xml b/doc/classes/Compositor.xml new file mode 100644 index 0000000000..c030896b6f --- /dev/null +++ b/doc/classes/Compositor.xml @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="Compositor" inherits="Resource" experimental="More customisation of the rendering pipeline will be added in the future." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Stores attributes used to customize how a Viewport is rendered. + </brief_description> + <description> + The compositor resource stores attributes used to customize how a [Viewport] is rendered. + </description> + <tutorials> + </tutorials> + <members> + <member name="compositor_effects" type="CompositorEffect[]" setter="set_compositor_effects" getter="get_compositor_effects" default="[]"> + The custom [CompositorEffect]s that are applied during rendering of viewports using this compositor. + </member> + </members> +</class> diff --git a/doc/classes/CompositorEffect.xml b/doc/classes/CompositorEffect.xml new file mode 100644 index 0000000000..b05dc44cf6 --- /dev/null +++ b/doc/classes/CompositorEffect.xml @@ -0,0 +1,84 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="CompositorEffect" inherits="Resource" experimental="The implementation may change as more of the rendering internals are exposed over time." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + This resource allows for creating a custom rendering effect. + </brief_description> + <description> + This resource defines a custom rendering effect that can be applied to [Viewport]s through the viewports' [Environment]. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. + </description> + <tutorials> + </tutorials> + <methods> + <method name="_render_callback" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="effect_callback_type" type="int" /> + <param index="1" name="render_data" type="RenderData" /> + <description> + Implement this function with your custom rendering code. [param effect_callback_type] should always match the effect callback type you've specified in [member effect_callback_type]. [param render_data] provides access to the rendering state, it is only valid during rendering and should not be stored. + </description> + </method> + </methods> + <members> + <member name="access_resolved_color" type="bool" setter="set_access_resolved_color" getter="get_access_resolved_color"> + If [code]true[/code] and MSAA is enabled, this will trigger a color buffer resolve before the effect is run. + [b]Note:[/b] In [method _render_callback], to access the resolved buffer use: + [codeblock] + var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var color_buffer = render_scene_buffers.get_texture("render_buffers", "color") + [/codeblock] + </member> + <member name="access_resolved_depth" type="bool" setter="set_access_resolved_depth" getter="get_access_resolved_depth"> + If [code]true[/code] and MSAA is enabled, this will trigger a depth buffer resolve before the effect is run. + [b]Note:[/b] In [method _render_callback], to access the resolved buffer use: + [codeblock] + var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var depth_buffer = render_scene_buffers.get_texture("render_buffers", "depth") + [/codeblock] + </member> + <member name="effect_callback_type" type="int" setter="set_effect_callback_type" getter="get_effect_callback_type" enum="CompositorEffect.EffectCallbackType"> + The type of effect that is implemented, determines at what stage of rendering the callback is called. + </member> + <member name="enabled" type="bool" setter="set_enabled" getter="get_enabled"> + If [code]true[/code] this rendering effect is applied to any viewport it is added to. + </member> + <member name="needs_motion_vectors" type="bool" setter="set_needs_motion_vectors" getter="get_needs_motion_vectors"> + If [code]true[/code] this triggers motion vectors being calculated during the opaque render state. + [b]Note:[/b] In [method _render_callback], to access the motion vector buffer use: + [codeblock] + var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var motion_buffer = render_scene_buffers.get_velocity_texture() + [/codeblock] + </member> + <member name="needs_normal_roughness" type="bool" setter="set_needs_normal_roughness" getter="get_needs_normal_roughness"> + If [code]true[/code] this triggers normal and roughness data to be output during our depth pre-pass, only applicable for the Forward+ renderer. + [b]Note:[/b] In [method _render_callback], to access the roughness buffer use: + [codeblock] + var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness") + [/codeblock] + </member> + <member name="needs_separate_specular" type="bool" setter="set_needs_separate_specular" getter="get_needs_separate_specular"> + If [code]true[/code] this triggers specular data being rendered to a separate buffer and combined after effects have been applied, only applicable for the Forward+ renderer. + </member> + </members> + <constants> + <constant name="EFFECT_CALLBACK_TYPE_PRE_OPAQUE" value="0" enum="EffectCallbackType"> + The callback is called before our opaque rendering pass, but after depth prepass (if applicable). + </constant> + <constant name="EFFECT_CALLBACK_TYPE_POST_OPAQUE" value="1" enum="EffectCallbackType"> + The callback is called after our opaque rendering pass, but before our sky is rendered. + </constant> + <constant name="EFFECT_CALLBACK_TYPE_POST_SKY" value="2" enum="EffectCallbackType"> + 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). + </constant> + <constant name="EFFECT_CALLBACK_TYPE_PRE_TRANSPARENT" value="3" enum="EffectCallbackType"> + The callback is called before our transparent rendering pass, but after our sky is rendered and we've created our back buffers. + </constant> + <constant name="EFFECT_CALLBACK_TYPE_POST_TRANSPARENT" value="4" enum="EffectCallbackType"> + The callback is called after our transparent rendering pass, but before any build in post effects and output to our render target. + </constant> + <constant name="EFFECT_CALLBACK_TYPE_MAX" value="5" enum="EffectCallbackType"> + Represents the size of the [enum EffectCallbackType] enum. + </constant> + </constants> +</class> diff --git a/doc/classes/CompressedCubemap.xml b/doc/classes/CompressedCubemap.xml index 6ab0cc5d88..406ab4909a 100644 --- a/doc/classes/CompressedCubemap.xml +++ b/doc/classes/CompressedCubemap.xml @@ -4,7 +4,7 @@ An optionally compressed [Cubemap]. </brief_description> <description> - A cubemap that is loaded from a [code].ccube[/code] file. This file format is internal to Godot; it is created by importing other image formats with the import system. [CompressedCubemap] can use one of 4 compresson methods: + A cubemap that is loaded from a [code].ccube[/code] file. This file format is internal to Godot; 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) diff --git a/doc/classes/CompressedCubemapArray.xml b/doc/classes/CompressedCubemapArray.xml index 32687229ed..195449ee99 100644 --- a/doc/classes/CompressedCubemapArray.xml +++ b/doc/classes/CompressedCubemapArray.xml @@ -4,7 +4,7 @@ An optionally compressed [CubemapArray]. </brief_description> <description> - A cubemap array that is loaded from a [code].ccubearray[/code] file. This file format is internal to Godot; it is created by importing other image formats with the import system. [CompressedCubemapArray] can use one of 4 compresson methods: + A cubemap array that is loaded from a [code].ccubearray[/code] file. This file format is internal to Godot; 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) diff --git a/doc/classes/CompressedTexture2DArray.xml b/doc/classes/CompressedTexture2DArray.xml index ab0684fa06..6570e8f931 100644 --- a/doc/classes/CompressedTexture2DArray.xml +++ b/doc/classes/CompressedTexture2DArray.xml @@ -4,7 +4,7 @@ Array of 2-dimensional textures, optionally compressed. </brief_description> <description> - A texture array that is loaded from a [code].ctexarray[/code] file. This file format is internal to Godot; it is created by importing other image formats with the import system. [CompressedTexture2DArray] can use one of 4 compresson methods: + A texture array that is loaded from a [code].ctexarray[/code] file. This file format is internal to Godot; 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) diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index a498bbeed3..cc32964e87 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -457,7 +457,7 @@ <method name="get_theme_color" qualifiers="const"> <return type="Color" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a [Color] from the first matching [Theme] in the tree if that [Theme] has a color item with the specified [param name] and [param theme_type]. If [param theme_type] is omitted the class name of the current control is used as the type, or [member theme_type_variation] if it is defined. If the type is a class name its parent classes are also checked, in order of inheritance. If the type is a variation its base types are checked, in order of dependency, then the control's class name and its parent classes are checked. For the current control its local overrides are considered first (see [method add_theme_color_override]), then its assigned [member theme]. After the current control, each parent control and its assigned [member theme] are considered; controls without a [member theme] assigned are skipped. If no matching [Theme] is found in the tree, the custom project [Theme] (see [member ProjectSettings.gui/theme/custom]) and the default [Theme] are used (see [ThemeDB]). @@ -484,7 +484,7 @@ <method name="get_theme_constant" qualifiers="const"> <return type="int" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a constant from the first matching [Theme] in the tree if that [Theme] has a constant item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -514,7 +514,7 @@ <method name="get_theme_font" qualifiers="const"> <return type="Font" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a [Font] from the first matching [Theme] in the tree if that [Theme] has a font item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -523,7 +523,7 @@ <method name="get_theme_font_size" qualifiers="const"> <return type="int" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a font size from the first matching [Theme] in the tree if that [Theme] has a font size item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -532,7 +532,7 @@ <method name="get_theme_icon" qualifiers="const"> <return type="Texture2D" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns an icon from the first matching [Theme] in the tree if that [Theme] has an icon item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -541,7 +541,7 @@ <method name="get_theme_stylebox" qualifiers="const"> <return type="StyleBox" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a [StyleBox] from the first matching [Theme] in the tree if that [Theme] has a stylebox item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -590,7 +590,7 @@ <method name="has_theme_color" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a color item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -607,7 +607,7 @@ <method name="has_theme_constant" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a constant item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -624,7 +624,7 @@ <method name="has_theme_font" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -641,7 +641,7 @@ <method name="has_theme_font_size" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font size item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -658,7 +658,7 @@ <method name="has_theme_icon" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has an icon item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -675,7 +675,7 @@ <method name="has_theme_stylebox" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a stylebox item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. @@ -937,9 +937,8 @@ <member name="anchor_top" type="float" setter="_set_anchor" getter="get_anchor" default="0.0"> 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 [enum Anchor] constants for convenience. </member> - <member name="auto_translate" type="bool" setter="set_auto_translate" getter="is_auto_translating" default="true"> + <member name="auto_translate" type="bool" setter="set_auto_translate" getter="is_auto_translating" default="true" deprecated="Use [member Node.auto_translate_mode] instead."> Toggles if any text should automatically change to its translated version depending on the current locale. - Also decides if the node's strings should be parsed for POT generation. </member> <member name="clip_contents" type="bool" setter="set_clip_contents" getter="is_clipping_contents" default="false"> Enables whether rendering of [CanvasItem] based children should be clipped to this control's rectangle. If [code]true[/code], parts of a child which would be visibly outside of this control's rectangle will not be rendered and won't receive input. @@ -950,16 +949,16 @@ <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" enum="Control.FocusMode" default="0"> The focus access mode for the control (None, Click or All). Only one Control can be focused at the same time, and it will receive keyboard, gamepad, and mouse signals. </member> - <member name="focus_neighbor_bottom" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> + <member name="focus_neighbor_bottom" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")" keywords="focus_neighbour_bottom"> Tells Godot 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 [member ProjectSettings.input/ui_down] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the bottom of this one. </member> - <member name="focus_neighbor_left" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> + <member name="focus_neighbor_left" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")" keywords="focus_neighbour_left"> Tells Godot 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 [member ProjectSettings.input/ui_left] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the left of this one. </member> - <member name="focus_neighbor_right" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> + <member name="focus_neighbor_right" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")" keywords="focus_neighbour_right"> Tells Godot 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 [member ProjectSettings.input/ui_right] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the right of this one. </member> - <member name="focus_neighbor_top" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> + <member name="focus_neighbor_top" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")" keywords="focus_neighbour_top"> Tells Godot 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 [member ProjectSettings.input/ui_up] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the top of this one. </member> <member name="focus_next" type="NodePath" setter="set_focus_next" getter="get_focus_next" default="NodePath("")"> @@ -1013,6 +1012,7 @@ Distance between the node's top edge and its parent control, based on [member anchor_top]. Offsets are often controlled by one or multiple parent [Container] nodes, so you should not modify them manually if your node is a direct child of a [Container]. Offsets update automatically when you move or resize the node. </member> + <member name="physics_interpolation_mode" type="int" setter="set_physics_interpolation_mode" getter="get_physics_interpolation_mode" overrides="Node" enum="Node.PhysicsInterpolationMode" default="2" /> <member name="pivot_offset" type="Vector2" setter="set_pivot_offset" getter="get_pivot_offset" default="Vector2(0, 0)"> By default, the node's pivot is its top-left corner. When you change its [member rotation] or [member scale], it will rotate or scale around this pivot. Set this property to [member size] / 2 to pivot around the Control's center. </member> @@ -1159,12 +1159,12 @@ [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. See also [constant NOTIFICATION_MOUSE_EXIT_SELF]. </constant> - <constant name="NOTIFICATION_MOUSE_ENTER_SELF" value="60" is_experimental="true"> + <constant name="NOTIFICATION_MOUSE_ENTER_SELF" value="60" 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 [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. See also [constant NOTIFICATION_MOUSE_ENTER]. </constant> - <constant name="NOTIFICATION_MOUSE_EXIT_SELF" value="61" is_experimental="true"> + <constant name="NOTIFICATION_MOUSE_EXIT_SELF" value="61" 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 [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. See also [constant NOTIFICATION_MOUSE_EXIT]. @@ -1182,6 +1182,14 @@ - One of the node's theme property overrides is changed. - The node enters the scene tree. [b]Note:[/b] As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree. + [b]Note:[/b] This notification is received alongside [constant Node.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 [method Node.is_node_ready]. + [codeblock] + 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) + [/codeblock] </constant> <constant name="NOTIFICATION_SCROLL_BEGIN" value="47"> Sent when this node is inside a [ScrollContainer] which has begun being scrolled when dragging the scrollable area [i]with a touch event[/i]. This notification is [i]not[/i] sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. diff --git a/doc/classes/Crypto.xml b/doc/classes/Crypto.xml index 59d19b03f4..65abc4c641 100644 --- a/doc/classes/Crypto.xml +++ b/doc/classes/Crypto.xml @@ -123,7 +123,7 @@ <param index="3" name="not_after" type="String" default=""20340101000000"" /> <description> Generates a self-signed [X509Certificate] from the given [CryptoKey] and [param issuer_name]. The certificate validity will be defined by [param not_before] and [param not_after] (first valid date and last valid date). The [param issuer_name] must contain at least "CN=" (common name, i.e. the domain name), "O=" (organization, i.e. your company name), "C=" (country, i.e. 2 lettered ISO-3166 code of the country the organization is based in). - A small example to generate an RSA key and a X509 self-signed certificate. + A small example to generate an RSA key and an X509 self-signed certificate. [codeblocks] [gdscript] var crypto = Crypto.new() diff --git a/doc/classes/CubemapArray.xml b/doc/classes/CubemapArray.xml index 7ee497385e..6e5e466fcf 100644 --- a/doc/classes/CubemapArray.xml +++ b/doc/classes/CubemapArray.xml @@ -4,10 +4,9 @@ An array of [Cubemap]s, stored together and with a single reference. </brief_description> <description> - [CubemapArray]s are made of an array of [Cubemap]s. Like [Cubemap]s, they are made of multiple textures, the amount of which must be divisible by 6 (one for each face of the cube). The primary benefit of [CubemapArray]s is that they can be accessed in shader code using a single texture reference. In other words, you can pass multiple [Cubemap]s into a shader using a single [CubemapArray]. - Moreover, [Cubemap]s are allocated in adjacent cache regions on the GPU. This makes [CubemapArray]s the most efficient way to store multiple [Cubemap]s. - Internally, Godot uses [CubemapArray]s for many effects, including the [Sky] if you set [member ProjectSettings.rendering/reflections/sky_reflections/texture_array_reflections] to [code]true[/code]. - To create such a texture file yourself, reimport your image files using the import presets of the File System dock. + [CubemapArray]s are made of an array of [Cubemap]s. Like [Cubemap]s, they are made of multiple textures, the amount of which must be divisible by 6 (one for each face of the cube). + The primary benefit of [CubemapArray]s is that they can be accessed in shader code using a single texture reference. In other words, you can pass multiple [Cubemap]s into a shader using a single [CubemapArray]. [Cubemap]s are allocated in adjacent cache regions on the GPU, which makes [CubemapArray]s the most efficient way to store multiple [Cubemap]s. + [b]Note:[/b] Godot uses [CubemapArray]s internally for many effects, including the [Sky] if you set [member ProjectSettings.rendering/reflections/sky_reflections/texture_array_reflections] to [code]true[/code]. To create such a texture file yourself, reimport your image files using the import presets of the File System dock. [b]Note:[/b] [CubemapArray] is not supported in the OpenGL 3 rendering backend. </description> <tutorials> diff --git a/doc/classes/Curve2D.xml b/doc/classes/Curve2D.xml index 197d03f0d8..0e75c65f50 100644 --- a/doc/classes/Curve2D.xml +++ b/doc/classes/Curve2D.xml @@ -107,16 +107,14 @@ <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> <description> - Similar to [method sample_baked], but returns [Transform2D] that includes a rotation along the curve, with [member Transform2D.origin] as the point position, [member Transform2D.x] as the sideways vector, and [member Transform2D.y] as the forward vector. Returns an empty transform if the length of the curve is [code]0[/code]. + Similar to [method sample_baked], but returns [Transform2D] that includes a rotation along the curve, with [member Transform2D.origin] as the point position and the [member Transform2D.x] vector pointing in the direction of the path at that point. Returns an empty transform if the length of the curve is [code]0[/code]. [codeblock] var baked = curve.sample_baked_with_rotation(offset) - # This will rotate and position the node with the up direction pointing along the curve. + # The returned Transform2D can be set directly. + transform = baked + # You can also read the origin and rotation separately from the returned Transform2D. position = baked.get_origin() rotation = baked.get_rotation() - # Alternatively, not preserving scale. - transform = baked * Transform2D.FLIP_Y - # To match the rotation of PathFollow2D, not preserving scale. - transform = Transform2D(baked.y, baked.x, baked.origin) [/codeblock] </description> </method> diff --git a/doc/classes/DTLSServer.xml b/doc/classes/DTLSServer.xml index f4c75a731d..41e241779a 100644 --- a/doc/classes/DTLSServer.xml +++ b/doc/classes/DTLSServer.xml @@ -45,7 +45,7 @@ { private DtlsServer _dtls = new DtlsServer(); private UdpServer _server = new UdpServer(); - private Godot.Collections.Array<PacketPeerDTLS> _peers = new Godot.Collections.Array<PacketPeerDTLS>(); + private Godot.Collections.Array<PacketPeerDtls> _peers = new Godot.Collections.Array<PacketPeerDtls>(); public override void _Ready() { @@ -59,8 +59,8 @@ { while (Server.IsConnectionAvailable()) { - PacketPeerUDP peer = _server.TakeConnection(); - PacketPeerDTLS dtlsPeer = _dtls.TakeConnection(peer); + PacketPeerUdp peer = _server.TakeConnection(); + PacketPeerDtls dtlsPeer = _dtls.TakeConnection(peer); if (dtlsPeer.GetStatus() != PacketPeerDtls.Status.Handshaking) { continue; // It is normal that 50% of the connections fails due to cookie exchange. diff --git a/doc/classes/Decal.xml b/doc/classes/Decal.xml index b89db8dc9e..10ac769e77 100644 --- a/doc/classes/Decal.xml +++ b/doc/classes/Decal.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="Decal" inherits="VisualInstance3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="Decal" inherits="VisualInstance3D" keywords="stain" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Node that projects a texture onto a [MeshInstance3D]. </brief_description> @@ -65,13 +65,13 @@ <member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="1048575"> Specifies which [member VisualInstance3D.layers] this decal will project on. By default, Decals affect all layers. This is used so you can specify which types of objects receive the Decal and which do not. This is especially useful so you can ensure that dynamic objects don't accidentally receive a Decal intended for the terrain under them. </member> - <member name="distance_fade_begin" type="float" setter="set_distance_fade_begin" getter="get_distance_fade_begin" default="40.0"> + <member name="distance_fade_begin" type="float" setter="set_distance_fade_begin" getter="get_distance_fade_begin" default="40.0" keywords="lod_begin"> The distance from the camera at which the Decal begins to fade away (in 3D units). </member> - <member name="distance_fade_enabled" type="bool" setter="set_enable_distance_fade" getter="is_distance_fade_enabled" default="false"> + <member name="distance_fade_enabled" type="bool" setter="set_enable_distance_fade" getter="is_distance_fade_enabled" default="false" keywords="lod_enabled"> If [code]true[/code], decals will smoothly fade away when far from the active [Camera3D] starting at [member distance_fade_begin]. The Decal will fade out over [member distance_fade_begin] + [member distance_fade_length], after which it will be culled and not sent to the shader at all. Use this to reduce the number of active Decals in a scene and thus improve performance. </member> - <member name="distance_fade_length" type="float" setter="set_distance_fade_length" getter="get_distance_fade_length" default="10.0"> + <member name="distance_fade_length" type="float" setter="set_distance_fade_length" getter="get_distance_fade_length" default="10.0" keywords="lod_length"> The distance over which the Decal fades (in 3D units). The Decal becomes slowly more transparent over this distance and is completely invisible at the end. Higher values result in a smoother fade-out transition, which is more suited when the camera moves fast. </member> <member name="emission_energy" type="float" setter="set_emission_energy" getter="get_emission_energy" default="1.0"> @@ -80,7 +80,7 @@ <member name="lower_fade" type="float" setter="set_lower_fade" getter="get_lower_fade" default="0.3"> Sets the curve over which the decal will fade as the surface gets further from the center of the [AABB]. Only positive values are valid (negative values will be clamped to [code]0.0[/code]). See also [member upper_fade]. </member> - <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)"> + <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)" keywords="color, colour"> Changes the [Color] of the Decal by multiplying the albedo and emission colors with this value. The alpha component is only taken into account when multiplying the albedo color, not the emission color. See also [member emission_energy] and [member albedo_mix] to change the emission and albedo intensity independently of each other. </member> <member name="normal_fade" type="float" setter="set_normal_fade" getter="get_normal_fade" default="0.0"> diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml index 955d80fcb7..14ce7c894f 100644 --- a/doc/classes/Dictionary.xml +++ b/doc/classes/Dictionary.xml @@ -194,6 +194,14 @@ Returns the corresponding value for the given [param key] in the dictionary. If the [param key] does not exist, returns [param default], or [code]null[/code] if the parameter is omitted. </description> </method> + <method name="get_or_add"> + <return type="Variant" /> + <param index="0" name="key" type="Variant" /> + <param index="1" name="default" type="Variant" default="null" /> + <description> + Gets a value and ensures the key is set. If the [param key] exists in the dictionary, this behaves like [method get]. Otherwise, the [param default] value is inserted into the dictionary and returned. + </description> + </method> <method name="has" qualifiers="const"> <return type="bool" /> <param index="0" name="key" type="Variant" /> @@ -332,6 +340,24 @@ [b]Note:[/b] [method merge] is [i]not[/i] recursive. Nested dictionaries are considered as keys that can be overwritten or not depending on the value of [param overwrite], but they will never be merged together. </description> </method> + <method name="merged" qualifiers="const"> + <return type="Dictionary" /> + <param index="0" name="dictionary" type="Dictionary" /> + <param index="1" name="overwrite" type="bool" default="false" /> + <description> + Returns a copy of this dictionary merged with the other [param dictionary]. By default, duplicate keys are not copied over, unless [param overwrite] is [code]true[/code]. See also [method merge]. + This method is useful for quickly making dictionaries with default values: + [codeblock] + var base = { "fruit": "apple", "vegetable": "potato" } + var extra = { "fruit": "orange", "dressing": "vinegar" } + # Prints { "fruit": "orange", "vegetable": "potato", "dressing": "vinegar" } + print(extra.merged(base)) + # Prints { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" } + print(extra.merged(base, true)) + [/codeblock] + See also [method merge]. + </description> + </method> <method name="size" qualifiers="const"> <return type="int" /> <description> diff --git a/doc/classes/DirAccess.xml b/doc/classes/DirAccess.xml index 89560c7a4e..03d7f68f43 100644 --- a/doc/classes/DirAccess.xml +++ b/doc/classes/DirAccess.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="DirAccess" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="DirAccess" inherits="RefCounted" keywords="directory, path, folder" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Provides methods for managing directories and their content. </brief_description> diff --git a/doc/classes/DirectionalLight2D.xml b/doc/classes/DirectionalLight2D.xml index 02909c95fa..d037f10c5b 100644 --- a/doc/classes/DirectionalLight2D.xml +++ b/doc/classes/DirectionalLight2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="DirectionalLight2D" inherits="Light2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="DirectionalLight2D" inherits="Light2D" keywords="sun" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Directional 2D light from a distance. </brief_description> diff --git a/doc/classes/DirectionalLight3D.xml b/doc/classes/DirectionalLight3D.xml index d3cca5fa6d..0a307a4ade 100644 --- a/doc/classes/DirectionalLight3D.xml +++ b/doc/classes/DirectionalLight3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="DirectionalLight3D" inherits="Light3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="DirectionalLight3D" inherits="Light3D" keywords="sun" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Directional light from a distance, as from the Sun. </brief_description> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 7f7dc1d288..9eb5f9e334 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -26,7 +26,7 @@ <return type="String" /> <description> Returns the user's [url=https://unix.stackexchange.com/questions/139191/whats-the-difference-between-primary-selection-and-clipboard-buffer]primary[/url] clipboard as a string if possible. This is the clipboard that is set when the user selects text in any application, rather than when pressing [kbd]Ctrl + C[/kbd]. The clipboard data can then be pasted by clicking the middle mouse button in any application that supports the primary clipboard mechanism. - [b]Note:[/b] This method is only implemented on Linux (X11). + [b]Note:[/b] This method is only implemented on Linux (X11/Wayland). </description> </method> <method name="clipboard_has" qualifiers="const"> @@ -53,7 +53,16 @@ <param index="0" name="clipboard_primary" type="String" /> <description> Sets the user's [url=https://unix.stackexchange.com/questions/139191/whats-the-difference-between-primary-selection-and-clipboard-buffer]primary[/url] clipboard content to the given string. This is the clipboard that is set when the user selects text in any application, rather than when pressing [kbd]Ctrl + C[/kbd]. The clipboard data can then be pasted by clicking the middle mouse button in any application that supports the primary clipboard mechanism. - [b]Note:[/b] This method is only implemented on Linux (X11). + [b]Note:[/b] This method is only implemented on Linux (X11/Wayland). + </description> + </method> + <method name="create_status_indicator"> + <return type="int" /> + <param index="0" name="icon" type="Image" /> + <param index="1" name="tooltip" type="String" /> + <param index="2" name="callback" type="Callable" /> + <description> + Creates a new application status indicator with the specified icon, tooltip, and activation callback. </description> </method> <method name="cursor_get_shape" qualifiers="const"> @@ -68,7 +77,8 @@ <param index="1" name="shape" type="int" enum="DisplayServer.CursorShape" default="0" /> <param index="2" name="hotspot" type="Vector2" default="Vector2(0, 0)" /> <description> - Sets a custom mouse cursor image for the defined [param shape]. This means the user's operating system and mouse cursor theme will no longer influence the mouse cursor's appearance. The image must be [code]256x256[/code] or smaller for correct appearance. [param hotspot] can optionally be set to define the area where the cursor will click. By default, [param hotspot] is set to [code]Vector2(0, 0)[/code], which is the top-left corner of the image. See also [method cursor_set_shape]. + Sets a custom mouse cursor image for the given [param shape]. This means the user's operating system and mouse cursor theme will no longer influence the mouse cursor's appearance. + [param cursor] can be either a [Texture2D] or an [Image], and it should not be larger than 256×256 to display correctly. Optionally, [param hotspot] can be set to offset the image's position relative to the click point. By default, [param hotspot] is set to the top-left corner of the image. See also [method cursor_set_shape]. </description> </method> <method name="cursor_set_shape"> @@ -78,6 +88,13 @@ Sets the default mouse cursor shape. The cursor's appearance will vary depending on the user's operating system and mouse cursor theme. See also [method cursor_get_shape] and [method cursor_set_custom_image]. </description> </method> + <method name="delete_status_indicator"> + <return type="void" /> + <param index="0" name="id" type="int" /> + <description> + Removes the application status indicator. + </description> + </method> <method name="dialog_input_text"> <return type="int" enum="Error" /> <param index="0" name="title" type="String" /> @@ -85,8 +102,8 @@ <param index="2" name="existing_text" type="String" /> <param index="3" name="callback" type="Callable" /> <description> - Shows a text input dialog which uses the operating system's native look-and-feel. [param callback] will be called with a [String] argument equal to the text field's contents when the dialog is closed for any reason. - [b]Note:[/b] This method is implemented only on macOS. + Shows a text input dialog which uses the operating system's native look-and-feel. [param callback] should accept a single [String] parameter which contains the text field's contents. + [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_INPUT] feature. Supported platforms include macOS and Windows. </description> </method> <method name="dialog_show"> @@ -96,8 +113,8 @@ <param index="2" name="buttons" type="PackedStringArray" /> <param index="3" name="callback" type="Callable" /> <description> - Shows a text dialog which uses the operating system's native look-and-feel. [param callback] will be called when the dialog is closed for any reason. - [b]Note:[/b] This method is implemented only on macOS. + Shows a text dialog which uses the operating system's native look-and-feel. [param callback] should accept a single [int] parameter which corresponds to the index of the pressed button. + [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG] feature. Supported platforms include macOS and Windows. </description> </method> <method name="enable_for_stealing_focus"> @@ -119,15 +136,41 @@ <param index="6" name="callback" type="Callable" /> <description> Displays OS native dialog for selecting files or directories in the file system. - Callbacks have the following arguments: [code]bool status, PackedStringArray selected_paths, int selected_filter_index[/code]. - [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG] feature. - [b]Note:[/b] This method is implemented on Linux, Windows and macOS. + Each filter string in the [param filters] array should be formatted like this: [code]*.txt,*.doc;Text Files[/code]. The description text of the filter is optional and can be omitted. See also [member FileDialog.filters]. + Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int[/code]. + [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS. [b]Note:[/b] [param current_directory] might be ignored. [b]Note:[/b] On Linux, [param show_hidden] is ignored. [b]Note:[/b] On macOS, native file dialogs have no title. [b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks. </description> </method> + <method name="file_dialog_with_options_show"> + <return type="int" enum="Error" /> + <param index="0" name="title" type="String" /> + <param index="1" name="current_directory" type="String" /> + <param index="2" name="root" type="String" /> + <param index="3" name="filename" type="String" /> + <param index="4" name="show_hidden" type="bool" /> + <param index="5" name="mode" type="int" enum="DisplayServer.FileDialogMode" /> + <param index="6" name="filters" type="PackedStringArray" /> + <param index="7" name="options" type="Dictionary[]" /> + <param index="8" name="callback" type="Callable" /> + <description> + Displays OS native dialog for selecting files or directories in the file system with additional user selectable options. + Each filter string in the [param filters] array should be formatted like this: [code]*.txt,*.doc;Text Files[/code]. The description text of the filter is optional and can be omitted. See also [member FileDialog.filters]. + [param options] is array of [Dictionary]s with the following keys: + - [code]"name"[/code] - option's name [String]. + - [code]"values"[/code] - [PackedStringArray] of values. If empty, boolean option (check box) is used. + - [code]"default"[/code] - default selected option index ([int]) or default boolean value ([bool]). + Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int, selected_option: Dictionary[/code]. + [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS. + [b]Note:[/b] [param current_directory] might be ignored. + [b]Note:[/b] On Linux (X11), [param show_hidden] is ignored. + [b]Note:[/b] On macOS, native file dialogs have no title. + [b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks. + </description> + </method> <method name="force_process_and_drop_events"> <return type="void" /> <description> @@ -142,6 +185,13 @@ [b]Note:[/b] This method is implemented on macOS and Windows. </description> </method> + <method name="get_base_color" qualifiers="const"> + <return type="Color" /> + <description> + Returns the OS theme base color (default control background). Returns [code]Color(0, 0, 0, 0)[/code] if the base color is unknown. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> <method name="get_display_cutouts" qualifiers="const"> <return type="Rect2[]" /> <description> @@ -164,8 +214,8 @@ <method name="get_name" qualifiers="const"> <return type="String" /> <description> - Returns the name of the [DisplayServer] currently in use. Most operating systems only have a single [DisplayServer], but Linux has access to more than one [DisplayServer] (although only X11 is currently implemented in Godot). - The names of built-in display servers are [code]Windows[/code], [code]macOS[/code], [code]X11[/code] (Linux), [code]Android[/code], [code]iOS[/code], [code]web[/code] (HTML5) and [code]headless[/code] (when started with the [code]--headless[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]). + Returns the name of the [DisplayServer] currently in use. Most operating systems only have a single [DisplayServer], but Linux has access to more than one [DisplayServer] (currently X11 and Wayland). + The names of built-in display servers are [code]Windows[/code], [code]macOS[/code], [code]X11[/code] (Linux), [code]Wayland[/code] (Linux), [code]Android[/code], [code]iOS[/code], [code]web[/code] (HTML5), and [code]headless[/code] (when started with the [code]--headless[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]). </description> </method> <method name="get_primary_screen" qualifiers="const"> @@ -216,7 +266,7 @@ [b]Note:[/b] Native dialogs are not included in this list. </description> </method> - <method name="global_menu_add_check_item"> + <method name="global_menu_add_check_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="label" type="String" /> @@ -235,10 +285,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_icon_check_item"> + <method name="global_menu_add_icon_check_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="icon" type="Texture2D" /> @@ -258,10 +311,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_icon_item"> + <method name="global_menu_add_icon_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="icon" type="Texture2D" /> @@ -281,10 +337,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_icon_radio_check_item"> + <method name="global_menu_add_icon_radio_check_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="icon" type="Texture2D" /> @@ -305,10 +364,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_item"> + <method name="global_menu_add_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="label" type="String" /> @@ -327,10 +389,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_multistate_item"> + <method name="global_menu_add_multistate_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="label" type="String" /> @@ -353,10 +418,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_radio_check_item"> + <method name="global_menu_add_radio_check_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="label" type="String" /> @@ -376,10 +444,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_separator"> + <method name="global_menu_add_separator" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="index" type="int" default="-1" /> @@ -391,10 +462,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_add_submenu_item"> + <method name="global_menu_add_submenu_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="label" type="String" /> @@ -408,10 +482,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_clear"> + <method name="global_menu_clear" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <description> @@ -421,10 +498,13 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> - <method name="global_menu_get_item_accelerator" qualifiers="const"> + <method name="global_menu_get_item_accelerator" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" enum="Key" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -433,7 +513,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_callback" qualifiers="const"> + <method name="global_menu_get_item_callback" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="Callable" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -442,7 +522,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_count" qualifiers="const"> + <method name="global_menu_get_item_count" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <description> @@ -450,7 +530,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_icon" qualifiers="const"> + <method name="global_menu_get_item_icon" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="Texture2D" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -459,7 +539,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_indentation_level" qualifiers="const"> + <method name="global_menu_get_item_indentation_level" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -468,25 +548,25 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_index_from_tag" qualifiers="const"> + <method name="global_menu_get_item_index_from_tag" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="tag" type="Variant" /> <description> - Returns the index of the item with the specified [param tag]. Index is automatically assigned to each item by the engine. Index can not be set manually. + Returns the index of the item with the specified [param tag]. Indices are automatically assigned to each item by the engine, and cannot be set manually. [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_index_from_text" qualifiers="const"> + <method name="global_menu_get_item_index_from_text" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="text" type="String" /> <description> - Returns the index of the item with the specified [param text]. Index is automatically assigned to each item by the engine. Index can not be set manually. + Returns the index of the item with the specified [param text]. Indices are automatically assigned to each item by the engine, and cannot be set manually. [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_key_callback" qualifiers="const"> + <method name="global_menu_get_item_key_callback" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="Callable" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -495,7 +575,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_max_states" qualifiers="const"> + <method name="global_menu_get_item_max_states" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -504,7 +584,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_state" qualifiers="const"> + <method name="global_menu_get_item_state" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="int" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -513,7 +593,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_submenu" qualifiers="const"> + <method name="global_menu_get_item_submenu" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="String" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -522,7 +602,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_tag" qualifiers="const"> + <method name="global_menu_get_item_tag" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="Variant" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -531,7 +611,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_text" qualifiers="const"> + <method name="global_menu_get_item_text" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="String" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -540,7 +620,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_get_item_tooltip" qualifiers="const"> + <method name="global_menu_get_item_tooltip" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="String" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -549,7 +629,14 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_is_item_checkable" qualifiers="const"> + <method name="global_menu_get_system_menu_roots" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> + <return type="Dictionary" /> + <description> + Returns Dictionary of supported system menu IDs and names. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="global_menu_is_item_checkable" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="bool" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -558,7 +645,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_is_item_checked" qualifiers="const"> + <method name="global_menu_is_item_checked" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="bool" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -567,7 +654,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_is_item_disabled" qualifiers="const"> + <method name="global_menu_is_item_disabled" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="bool" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -577,7 +664,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_is_item_hidden" qualifiers="const"> + <method name="global_menu_is_item_hidden" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="bool" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -587,7 +674,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_is_item_radio_checkable" qualifiers="const"> + <method name="global_menu_is_item_radio_checkable" qualifiers="const" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="bool" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -597,7 +684,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_remove_item"> + <method name="global_menu_remove_item" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -607,7 +694,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_accelerator"> + <method name="global_menu_set_item_accelerator" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -617,7 +704,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_callback"> + <method name="global_menu_set_item_callback" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -628,7 +715,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_checkable"> + <method name="global_menu_set_item_checkable" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -638,7 +725,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_checked"> + <method name="global_menu_set_item_checked" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -648,7 +735,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_disabled"> + <method name="global_menu_set_item_disabled" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -658,7 +745,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_hidden"> + <method name="global_menu_set_item_hidden" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -668,7 +755,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_hover_callbacks"> + <method name="global_menu_set_item_hover_callbacks" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -679,7 +766,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_icon"> + <method name="global_menu_set_item_icon" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -690,7 +777,7 @@ [b]Note:[/b] This method is not supported by macOS "_dock" menu items. </description> </method> - <method name="global_menu_set_item_indentation_level"> + <method name="global_menu_set_item_indentation_level" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -700,7 +787,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_key_callback"> + <method name="global_menu_set_item_key_callback" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -711,7 +798,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_max_states"> + <method name="global_menu_set_item_max_states" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -721,7 +808,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_radio_checkable"> + <method name="global_menu_set_item_radio_checkable" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -732,7 +819,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_state"> + <method name="global_menu_set_item_state" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -742,7 +829,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_submenu"> + <method name="global_menu_set_item_submenu" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -752,7 +839,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_tag"> + <method name="global_menu_set_item_tag" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -762,7 +849,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_text"> + <method name="global_menu_set_item_text" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -772,7 +859,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_item_tooltip"> + <method name="global_menu_set_item_tooltip" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="idx" type="int" /> @@ -782,7 +869,7 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> - <method name="global_menu_set_popup_callbacks"> + <method name="global_menu_set_popup_callbacks" deprecated="Use [NativeMenu] or [PopupMenu] instead."> <return type="void" /> <param index="0" name="menu_root" type="String" /> <param index="1" name="open_callback" type="Callable" /> @@ -798,6 +885,17 @@ Returns [code]true[/code] if the specified [param feature] is supported by the current [DisplayServer], [code]false[/code] otherwise. </description> </method> + <method name="help_set_search_callbacks"> + <return type="void" /> + <param index="0" name="search_callback" type="Callable" /> + <param index="1" name="action_callback" type="Callable" /> + <description> + Sets native help system search callbacks. + [param search_callback] has the following arguments: [code]String search_string, int result_limit[/code] and return a [Dictionary] with "key, display name" pairs for the search results. Called when the user enters search terms in the [code]Help[/code] menu. + [param action_callback] has the following arguments: [code]String key[/code]. Called when the user selects a search result in the [code]Help[/code] menu. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> <method name="ime_get_selection" qualifiers="const"> <return type="Vector2i" /> <description> @@ -816,14 +914,14 @@ <return type="bool" /> <description> Returns [code]true[/code] if OS is using dark mode. - [b]Note:[/b] This method is implemented on Android, iOS, macOS, Windows, and Linux (X11). + [b]Note:[/b] This method is implemented on Android, iOS, macOS, Windows, and Linux (X11/Wayland). </description> </method> <method name="is_dark_mode_supported" qualifiers="const"> <return type="bool" /> <description> Returns [code]true[/code] if OS supports dark mode. - [b]Note:[/b] This method is implemented on Android, iOS, macOS, Windows, and Linux (X11). + [b]Note:[/b] This method is implemented on Android, iOS, macOS, Windows, and Linux (X11/Wayland). </description> </method> <method name="is_touchscreen_available" qualifiers="const"> @@ -836,7 +934,7 @@ <return type="int" /> <description> Returns active keyboard layout index. - [b]Note:[/b] This method is implemented on Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS, and Windows. </description> </method> <method name="keyboard_get_keycode_from_physical" qualifiers="const"> @@ -844,7 +942,7 @@ <param index="0" name="keycode" type="int" enum="Key" /> <description> Converts a physical (US QWERTY) [param keycode] to one in the active keyboard layout. - [b]Note:[/b] This method is implemented on Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS and Windows. </description> </method> <method name="keyboard_get_label_from_physical" qualifiers="const"> @@ -852,14 +950,14 @@ <param index="0" name="keycode" type="int" enum="Key" /> <description> Converts a physical (US QWERTY) [param keycode] to localized label printed on the key in the active keyboard layout. - [b]Note:[/b] This method is implemented on Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS and Windows. </description> </method> <method name="keyboard_get_layout_count" qualifiers="const"> <return type="int" /> <description> Returns the number of keyboard layouts. - [b]Note:[/b] This method is implemented on Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS and Windows. </description> </method> <method name="keyboard_get_layout_language" qualifiers="const"> @@ -867,7 +965,7 @@ <param index="0" name="index" type="int" /> <description> Returns the ISO-639/BCP-47 language code of the keyboard layout at position [param index]. - [b]Note:[/b] This method is implemented on Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS and Windows. </description> </method> <method name="keyboard_get_layout_name" qualifiers="const"> @@ -875,7 +973,7 @@ <param index="0" name="index" type="int" /> <description> Returns the localized name of the keyboard layout at position [param index]. - [b]Note:[/b] This method is implemented on Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS and Windows. </description> </method> <method name="keyboard_set_current_layout"> @@ -883,7 +981,7 @@ <param index="0" name="index" type="int" /> <description> Sets the active keyboard layout. - [b]Note:[/b] This method is implemented on Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS and Windows. </description> </method> <method name="mouse_get_button_state" qualifiers="const"> @@ -932,7 +1030,7 @@ xxhdpi - 480 dpi xxxhdpi - 640 dpi [/codeblock] - [b]Note:[/b] This method is implemented on Android, Linux (X11), macOS and Windows. Returns [code]72[/code] on unsupported platforms. + [b]Note:[/b] This method is implemented on Android, Linux (X11/Wayland), macOS and Windows. Returns [code]72[/code] on unsupported platforms. </description> </method> <method name="screen_get_image" qualifiers="const"> @@ -983,6 +1081,7 @@ +-------------+ +-------+ [/codeblock] See also [method screen_get_size]. + [b]Note:[/b] On Linux (Wayland) this method always returns [code](0, 0)[/code]. </description> </method> <method name="screen_get_refresh_rate" qualifiers="const"> @@ -1049,6 +1148,7 @@ <param index="0" name="image" type="Image" /> <description> Sets the window icon (usually displayed in the top-left corner) with an [Image]. To use icons in the operating system's native format, use [method set_native_icon] instead. + [b]Note:[/b] Requires support for [constant FEATURE_ICON]. </description> </method> <method name="set_native_icon"> @@ -1056,6 +1156,39 @@ <param index="0" name="filename" type="String" /> <description> Sets the window icon (usually displayed in the top-left corner) in the operating system's [i]native[/i] format. The file at [param filename] must be in [code].ico[/code] format on Windows or [code].icns[/code] on macOS. By using specially crafted [code].ico[/code] or [code].icns[/code] icons, [method set_native_icon] allows specifying different icons depending on the size the icon is displayed at. This size is determined by the operating system and user preferences (including the display scale factor). To use icons in other formats, use [method set_icon] instead. + [b]Note:[/b] Requires support for [constant FEATURE_NATIVE_ICON]. + </description> + </method> + <method name="set_system_theme_change_callback"> + <return type="void" /> + <param index="0" name="callable" type="Callable" /> + <description> + Sets the [param callable] that should be called when system theme settings are changed. Callback method should have zero arguments. + [b]Note:[/b] This method is implemented on Android, iOS, macOS, Windows, and Linux (X11/Wayland). + </description> + </method> + <method name="status_indicator_set_callback"> + <return type="void" /> + <param index="0" name="id" type="int" /> + <param index="1" name="callback" type="Callable" /> + <description> + Sets the application status indicator activation callback. + </description> + </method> + <method name="status_indicator_set_icon"> + <return type="void" /> + <param index="0" name="id" type="int" /> + <param index="1" name="icon" type="Image" /> + <description> + Sets the application status indicator icon. + </description> + </method> + <method name="status_indicator_set_tooltip"> + <return type="void" /> + <param index="0" name="id" type="int" /> + <param index="1" name="tooltip" type="String" /> + <description> + Sets the application status indicator tooltip. </description> </method> <method name="tablet_get_current_driver" qualifiers="const"> @@ -1085,6 +1218,10 @@ <param index="0" name="name" type="String" /> <description> Set active tablet driver name. + Supported drivers: + - [code]winink[/code]: Windows Ink API, default (Windows 8.1+ required). + - [code]wintab[/code]: Wacom Wintab API (compatible device driver required). + - [code]dummy[/code]: Dummy driver, tablet input is disabled. [b]Note:[/b] This method is implemented only on Windows. </description> </method> @@ -1097,7 +1234,7 @@ - [code]id[/code] is voice identifier. - [code]language[/code] is language code in [code]lang_Variant[/code] format. The [code]lang[/code] part is a 2 or 3-letter code based on the ISO-639 standard, in lowercase. The [code skip-lint]Variant[/code] part is an engine-dependent string describing country, region or/and dialect. Note that Godot depends on system libraries for text-to-speech functionality. These libraries are installed by default on Windows and macOS, but not on all Linux distributions. If they are not present, this method will return an empty list. This applies to both Godot users on Linux, as well as end-users on Linux running Godot games that use text-to-speech. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1106,7 +1243,7 @@ <param index="0" name="language" type="String" /> <description> Returns an [PackedStringArray] of voice identifiers for the [param language]. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1114,7 +1251,7 @@ <return type="bool" /> <description> Returns [code]true[/code] if the synthesizer is in a paused state. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1122,7 +1259,7 @@ <return type="bool" /> <description> Returns [code]true[/code] if the synthesizer is generating speech, or have utterance waiting in the queue. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1130,7 +1267,7 @@ <return type="void" /> <description> Puts the synthesizer into a paused state. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1138,7 +1275,7 @@ <return type="void" /> <description> Resumes the synthesizer if it was paused. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1151,7 +1288,7 @@ - [constant TTS_UTTERANCE_STARTED], [constant TTS_UTTERANCE_ENDED], and [constant TTS_UTTERANCE_CANCELED] callable's method should take one [int] parameter, the utterance ID. - [constant TTS_UTTERANCE_BOUNDARY] callable's method should take two [int] parameters, the index of the character and the utterance ID. [b]Note:[/b] The granularity of the boundary callbacks is engine dependent. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1171,9 +1308,9 @@ - [param pitch] ranges from [code]0.0[/code] (lowest) to [code]2.0[/code] (highest), [code]1.0[/code] is default pitch for the current voice. - [param rate] ranges from [code]0.1[/code] (lowest) to [code]10.0[/code] (highest), [code]1.0[/code] is a normal speaking rate. Other values act as a percentage relative. - [param utterance_id] is passed as a parameter to the callback functions. - [b]Note:[/b] On Windows and Linux (X11), utterance [param text] can use SSML markup. SSML support is engine and voice dependent. If the engine does not support SSML, you should strip out all XML markup before calling [method tts_speak]. + [b]Note:[/b] On Windows and Linux (X11/Wayland), utterance [param text] can use SSML markup. SSML support is engine and voice dependent. If the engine does not support SSML, you should strip out all XML markup before calling [method tts_speak]. [b]Note:[/b] The granularity of pitch, rate, and volume is engine and voice dependent. Values may be truncated. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1181,7 +1318,7 @@ <return type="void" /> <description> Stops synthesis in progress and removes all utterances from the queue. - [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11/Linux), macOS, and Windows. [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> @@ -1221,7 +1358,7 @@ <param index="0" name="position" type="Vector2i" /> <description> Sets the mouse cursor position to the given [param position] relative to an origin at the upper left corner of the currently focused game Window Manager window. - [b]Note:[/b] [method warp_mouse] is only supported on Windows, macOS and Linux. It has no effect on Android, iOS and Web. + [b]Note:[/b] [method warp_mouse] is only supported on Windows, macOS, and Linux (X11/Wayland). It has no effect on Android, iOS, and Web. </description> </method> <method name="window_can_draw" qualifiers="const"> @@ -1286,7 +1423,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Returns internal structure pointers for use in plugins. - [b]Note:[/b] This method is implemented on Android, Linux (X11), macOS and Windows. + [b]Note:[/b] This method is implemented on Android, Linux (X11/Wayland), macOS, and Windows. </description> </method> <method name="window_get_popup_safe_rect" qualifiers="const"> @@ -1404,7 +1541,7 @@ <description> Sets the [param callback] that should be called when files are dropped from the operating system's file manager to the window specified by [param window_id]. [b]Warning:[/b] Advanced users only! Adding such a callback to a [Window] node will override its default implementation, which can introduce bugs. - [b]Note:[/b] This method is implemented on Windows, macOS, Linux (X11) and Web. + [b]Note:[/b] This method is implemented on Windows, macOS, Linux (X11/Wayland), and Web. </description> </method> <method name="window_set_exclusive"> @@ -1547,6 +1684,7 @@ [/codeblock] See also [method window_get_position] and [method window_set_size]. [b]Note:[/b] It's recommended to change this value using [member Window.position] instead. + [b]Note:[/b] On Linux (Wayland): this method is a no-op. </description> </method> <method name="window_set_rect_changed_callback"> @@ -1618,7 +1756,7 @@ </method> </methods> <constants> - <constant name="FEATURE_GLOBAL_MENU" value="0" enum="Feature"> + <constant name="FEATURE_GLOBAL_MENU" value="0" enum="Feature" deprecated="Use [NativeMenu] or [PopupMenu] instead."> Display server supports global menu. This allows the application to display its menu items in the operating system's top bar. [b]macOS[/b] </constant> <constant name="FEATURE_SUBWINDOWS" value="1" enum="Feature"> @@ -1628,34 +1766,34 @@ Display server supports touchscreen input. [b]Windows, Linux (X11), Android, iOS, Web[/b] </constant> <constant name="FEATURE_MOUSE" value="3" enum="Feature"> - Display server supports mouse input. [b]Windows, macOS, Linux (X11), Android, Web[/b] + Display server supports mouse input. [b]Windows, macOS, Linux (X11/Wayland), Android, Web[/b] </constant> <constant name="FEATURE_MOUSE_WARP" value="4" enum="Feature"> - Display server supports warping mouse coordinates to keep the mouse cursor constrained within an area, but looping when one of the edges is reached. [b]Windows, macOS, Linux (X11)[/b] + Display server supports warping mouse coordinates to keep the mouse cursor constrained within an area, but looping when one of the edges is reached. [b]Windows, macOS, Linux (X11/Wayland)[/b] </constant> <constant name="FEATURE_CLIPBOARD" value="5" enum="Feature"> - Display server supports setting and getting clipboard data. See also [constant FEATURE_CLIPBOARD_PRIMARY]. [b]Windows, macOS, Linux (X11), Android, iOS, Web[/b] + Display server supports setting and getting clipboard data. See also [constant FEATURE_CLIPBOARD_PRIMARY]. [b]Windows, macOS, Linux (X11/Wayland), Android, iOS, Web[/b] </constant> <constant name="FEATURE_VIRTUAL_KEYBOARD" value="6" enum="Feature"> Display server supports popping up a virtual keyboard when requested to input text without a physical keyboard. [b]Android, iOS, Web[/b] </constant> <constant name="FEATURE_CURSOR_SHAPE" value="7" enum="Feature"> - Display server supports setting the mouse cursor shape to be different from the default. [b]Windows, macOS, Linux (X11), Android, Web[/b] + Display server supports setting the mouse cursor shape to be different from the default. [b]Windows, macOS, Linux (X11/Wayland), Android, Web[/b] </constant> <constant name="FEATURE_CUSTOM_CURSOR_SHAPE" value="8" enum="Feature"> - Display server supports setting the mouse cursor shape to a custom image. [b]Windows, macOS, Linux (X11), Web[/b] + Display server supports setting the mouse cursor shape to a custom image. [b]Windows, macOS, Linux (X11/Wayland), Web[/b] </constant> <constant name="FEATURE_NATIVE_DIALOG" value="9" enum="Feature"> - Display server supports spawning dialogs using the operating system's native look-and-feel. [b]macOS[/b] + Display server supports spawning text dialogs using the operating system's native look-and-feel. See [method dialog_show]. [b]Windows, macOS[/b] </constant> <constant name="FEATURE_IME" value="10" enum="Feature"> Display server supports [url=https://en.wikipedia.org/wiki/Input_method]Input Method Editor[/url], which is commonly used for inputting Chinese/Japanese/Korean text. This is handled by the operating system, rather than by Godot. [b]Windows, macOS, Linux (X11)[/b] </constant> <constant name="FEATURE_WINDOW_TRANSPARENCY" value="11" enum="Feature"> - Display server supports windows can use per-pixel transparency to make windows behind them partially or fully visible. [b]Windows, macOS, Linux (X11)[/b] + Display server supports windows can use per-pixel transparency to make windows behind them partially or fully visible. [b]Windows, macOS, Linux (X11/Wayland)[/b] </constant> <constant name="FEATURE_HIDPI" value="12" enum="Feature"> - Display server supports querying the operating system's display scale factor. This allows for [i]reliable[/i] automatic hiDPI display detection, as opposed to guessing based on the screen resolution and reported display DPI (which can be unreliable due to broken monitor EDID). [b]Windows, macOS[/b] + Display server supports querying the operating system's display scale factor. This allows for [i]reliable[/i] automatic hiDPI display detection, as opposed to guessing based on the screen resolution and reported display DPI (which can be unreliable due to broken monitor EDID). [b]Windows, Linux (Wayland), macOS[/b] </constant> <constant name="FEATURE_ICON" value="13" enum="Feature"> Display server supports changing the window icon (usually displayed in the top-left corner). [b]Windows, macOS, Linux (X11)[/b] @@ -1667,13 +1805,13 @@ Display server supports changing the screen orientation. [b]Android, iOS[/b] </constant> <constant name="FEATURE_SWAP_BUFFERS" value="16" enum="Feature"> - Display server supports V-Sync status can be changed from the default (which is forced to be enabled platforms not supporting this feature). [b]Windows, macOS, Linux (X11)[/b] + Display server supports V-Sync status can be changed from the default (which is forced to be enabled platforms not supporting this feature). [b]Windows, macOS, Linux (X11/Wayland)[/b] </constant> <constant name="FEATURE_CLIPBOARD_PRIMARY" value="18" enum="Feature"> - Display server supports Primary clipboard can be used. This is a different clipboard from [constant FEATURE_CLIPBOARD]. [b]Linux (X11)[/b] + Display server supports Primary clipboard can be used. This is a different clipboard from [constant FEATURE_CLIPBOARD]. [b]Linux (X11/Wayland)[/b] </constant> <constant name="FEATURE_TEXT_TO_SPEECH" value="19" enum="Feature"> - Display server supports text-to-speech. See [code]tts_*[/code] methods. [b]Windows, macOS, Linux (X11), Android, iOS, Web[/b] + Display server supports text-to-speech. See [code]tts_*[/code] methods. [b]Windows, macOS, Linux (X11/Wayland), Android, iOS, Web[/b] </constant> <constant name="FEATURE_EXTEND_TO_TITLE" value="20" enum="Feature"> Display server supports expanding window content to the title. See [constant WINDOW_FLAG_EXTEND_TO_TITLE]. [b]macOS[/b] @@ -1681,6 +1819,18 @@ <constant name="FEATURE_SCREEN_CAPTURE" value="21" enum="Feature"> Display server supports reading screen pixels. See [method screen_get_pixel]. </constant> + <constant name="FEATURE_STATUS_INDICATOR" value="22" enum="Feature"> + Display server supports application status indicators. + </constant> + <constant name="FEATURE_NATIVE_HELP" value="23" enum="Feature"> + Display server supports native help system search callbacks. See [method help_set_search_callbacks]. + </constant> + <constant name="FEATURE_NATIVE_DIALOG_INPUT" value="24" enum="Feature"> + Display server supports spawning text input dialogs using the operating system's native look-and-feel. See [method dialog_input_text]. [b]Windows, macOS[/b] + </constant> + <constant name="FEATURE_NATIVE_DIALOG_FILE" value="25" enum="Feature"> + Display server supports spawning dialogs for selecting files or directories using the operating system's native look-and-feel. See [method file_dialog_show] and [method file_dialog_with_options_show]. [b]Windows, macOS, Linux (X11/Wayland)[/b] + </constant> <constant name="MOUSE_MODE_VISIBLE" value="0" enum="MouseMode"> Makes the mouse cursor visible if it is hidden. </constant> @@ -1699,21 +1849,28 @@ </constant> <constant name="SCREEN_WITH_MOUSE_FOCUS" value="-4"> Represents the screen containing the mouse pointer. + [b]Note:[/b] On Linux (Wayland), this constant always represents the screen at index [code]0[/code]. </constant> <constant name="SCREEN_WITH_KEYBOARD_FOCUS" value="-3"> Represents the screen containing the window with the keyboard focus. + [b]Note:[/b] On Linux (Wayland), this constant always represents the screen at index [code]0[/code]. </constant> <constant name="SCREEN_PRIMARY" value="-2"> Represents the primary screen. + [b]Note:[/b] On Linux (Wayland), this constant always represents the screen at index [code]0[/code]. </constant> <constant name="SCREEN_OF_MAIN_WINDOW" value="-1"> Represents the screen where the main window is located. This is usually the default value in functions that allow specifying one of several screens. + [b]Note:[/b] On Linux (Wayland), this constant always represents the screen at index [code]0[/code]. </constant> <constant name="MAIN_WINDOW_ID" value="0"> The ID of the main window spawned by the engine, which can be passed to methods expecting a [code]window_id[/code]. </constant> <constant name="INVALID_WINDOW_ID" value="-1"> - The ID that refers to a nonexisting window. This is be returned by some [DisplayServer] methods if no window matches the requested result. + The ID that refers to a nonexistent window. This is returned by some [DisplayServer] methods if no window matches the requested result. + </constant> + <constant name="INVALID_INDICATOR_ID" value="-1"> + The ID that refers to a nonexistent application status indicator. </constant> <constant name="SCREEN_LANDSCAPE" value="0" enum="ScreenOrientation"> Default landscape orientation. @@ -1866,7 +2023,7 @@ <constant name="WINDOW_FLAG_TRANSPARENT" value="3" enum="WindowFlags"> The window background can be transparent. [b]Note:[/b] This flag has no effect if [member ProjectSettings.display/window/per_pixel_transparency/allowed] is set to [code]false[/code]. - [b]Note:[/b] Transparency support is implemented on Linux (X11), macOS and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities. + [b]Note:[/b] Transparency support is implemented on Linux (X11/Wayland), macOS, and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities. </constant> <constant name="WINDOW_FLAG_NO_FOCUS" value="4" enum="WindowFlags"> The window can't be focused. No-focus window will ignore all input, except mouse clicks. @@ -1914,16 +2071,16 @@ [b]Note:[/b] This flag is implemented only on macOS. </constant> <constant name="VSYNC_DISABLED" value="0" enum="VSyncMode"> - No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (notwithstanding [member Engine.max_fps]). + No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (regardless of [member Engine.max_fps]). </constant> <constant name="VSYNC_ENABLED" value="1" enum="VSyncMode"> - Default vertical synchronization mode, the image is displayed only on vertical blanking intervals (no tearing is visible). Framerate is limited by the monitor refresh rate (notwithstanding [member Engine.max_fps]). + Default vertical synchronization mode, the image is displayed only on vertical blanking intervals (no tearing is visible). Framerate is limited by the monitor refresh rate (regardless of [member Engine.max_fps]). </constant> <constant name="VSYNC_ADAPTIVE" value="2" enum="VSyncMode"> - Behaves like [constant VSYNC_DISABLED] when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (notwithstanding [member Engine.max_fps]). Behaves like [constant VSYNC_ENABLED] when using the Compatibility rendering method. + Behaves like [constant VSYNC_DISABLED] when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (regardless of [member Engine.max_fps]). Behaves like [constant VSYNC_ENABLED] when using the Compatibility rendering method. </constant> <constant name="VSYNC_MAILBOX" value="3" enum="VSyncMode"> - Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible). Framerate is unlimited (notwithstanding [member Engine.max_fps]). + Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible). Framerate is unlimited (regardless of [member Engine.max_fps]). Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag (also called "Fast" V-Sync mode). [constant VSYNC_MAILBOX] works best when at least twice as many frames as the display refresh rate are rendered. Behaves like [constant VSYNC_ENABLED] when using the Compatibility rendering method. </constant> <constant name="DISPLAY_HANDLE" value="0" enum="HandleType"> @@ -1948,7 +2105,7 @@ <constant name="OPENGL_CONTEXT" value="3" enum="HandleType"> OpenGL context (only with the GL Compatibility renderer): - Windows: [code]HGLRC[/code] for the window (native GL), or [code]EGLContext[/code] for the window (ANGLE). - - Linux: [code]GLXContext*[/code] for the window. + - Linux (X11): [code]GLXContext*[/code] for the window. - macOS: [code]NSOpenGLContext*[/code] for the window (native GL), or [code]EGLContext[/code] for the window (ANGLE). - Android: [code]EGLContext[/code] for the window. </constant> diff --git a/doc/classes/EditorExportPlatform.xml b/doc/classes/EditorExportPlatform.xml index 6801ac672c..0e5de79b25 100644 --- a/doc/classes/EditorExportPlatform.xml +++ b/doc/classes/EditorExportPlatform.xml @@ -8,7 +8,7 @@ Used in scripting by [EditorExportPlugin] to configure platform-specific customization of scenes and resources. See [method EditorExportPlugin._begin_customize_scenes] and [method EditorExportPlugin._begin_customize_resources] for more details. </description> <tutorials> - <link title="$DOCS_URL/tutorials/platform/consoles.html">Console support in Godot</link> + <link title="Console support in Godot">$DOCS_URL/tutorials/platform/consoles.html</link> </tutorials> <methods> <method name="get_os_name" qualifiers="const"> diff --git a/doc/classes/EditorExportPlugin.xml b/doc/classes/EditorExportPlugin.xml index 853348f64c..436f471e5d 100644 --- a/doc/classes/EditorExportPlugin.xml +++ b/doc/classes/EditorExportPlugin.xml @@ -178,6 +178,30 @@ - [code]update_visibility[/code]: An optional boolean value. If set to [code]true[/code], the preset will emit [signal Object.property_list_changed] when the option is changed. </description> </method> + <method name="_get_export_options_overrides" qualifiers="virtual const"> + <return type="Dictionary" /> + <param index="0" name="platform" type="EditorExportPlatform" /> + <description> + Return a [Dictionary] of override values for export options, that will be used instead of user-provided values. Overridden options will be hidden from the user interface. + [codeblock] + class MyExportPlugin extends EditorExportPlugin: + func _get_name() -> String: + return "MyExportPlugin" + + func _supports_platform(platform) -> bool: + if platform is EditorExportPlatformPC: + # Run on all desktop platforms including Windows, MacOS and Linux. + return true + return false + + func _get_export_options_overrides(platform) -> Dictionary: + # Override "Embed PCK" to always be enabled. + return { + "binary_format/embed_pck": true, + } + [/codeblock] + </description> + </method> <method name="_get_name" qualifiers="virtual const"> <return type="String" /> <description> diff --git a/doc/classes/EditorFileDialog.xml b/doc/classes/EditorFileDialog.xml index b51341dc24..4befcf5e69 100644 --- a/doc/classes/EditorFileDialog.xml +++ b/doc/classes/EditorFileDialog.xml @@ -19,6 +19,16 @@ For example, a [param filter] of [code]"*.tscn, *.scn"[/code] and a [param description] of [code]"Scenes"[/code] results in filter text "Scenes (*.tscn, *.scn)". </description> </method> + <method name="add_option"> + <return type="void" /> + <param index="0" name="name" type="String" /> + <param index="1" name="values" type="PackedStringArray" /> + <param index="2" name="default_value_index" type="int" /> + <description> + Adds an additional [OptionButton] to the file dialog. If [param values] is empty, a [CheckBox] is added instead. + [param default_value_index] should be an index of the value in the [param values]. If [param values] is empty it should be either [code]1[/code] (checked), or [code]0[/code] (unchecked). + </description> + </method> <method name="add_side_menu"> <return type="void" /> <param index="0" name="menu" type="Control" /> @@ -40,6 +50,33 @@ [b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member CanvasItem.visible] property. </description> </method> + <method name="get_option_default" qualifiers="const"> + <return type="int" /> + <param index="0" name="option" type="int" /> + <description> + Returns the default value index of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="get_option_name" qualifiers="const"> + <return type="String" /> + <param index="0" name="option" type="int" /> + <description> + Returns the name of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="get_option_values" qualifiers="const"> + <return type="PackedStringArray" /> + <param index="0" name="option" type="int" /> + <description> + Returns an array of values of the [OptionButton] with index [param option]. + </description> + </method> + <method name="get_selected_options" qualifiers="const"> + <return type="Dictionary" /> + <description> + Returns a [Dictionary] with the selected values of the additional [OptionButton]s and/or [CheckBox]es. [Dictionary] keys are names and values are selected value indices. + </description> + </method> <method name="get_vbox"> <return type="VBoxContainer" /> <description> @@ -53,6 +90,30 @@ Notify the [EditorFileDialog] that its view of the data is no longer accurate. Updates the view contents on next view update. </description> </method> + <method name="set_option_default"> + <return type="void" /> + <param index="0" name="option" type="int" /> + <param index="1" name="default_value_index" type="int" /> + <description> + Sets the default value index of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="set_option_name"> + <return type="void" /> + <param index="0" name="option" type="int" /> + <param index="1" name="name" type="String" /> + <description> + Sets the name of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="set_option_values"> + <return type="void" /> + <param index="0" name="option" type="int" /> + <param index="1" name="values" type="PackedStringArray" /> + <description> + Sets the option values of the [OptionButton] with index [param option]. + </description> + </method> </methods> <members> <member name="access" type="int" setter="set_access" getter="get_access" enum="EditorFileDialog.Access" default="0"> @@ -80,6 +141,9 @@ <member name="filters" type="PackedStringArray" setter="set_filters" getter="get_filters" default="PackedStringArray()"> The available file type filters. For example, this shows only [code].png[/code] and [code].gd[/code] files: [code]set_filters(PackedStringArray(["*.png ; PNG Images","*.gd ; GDScript Files"]))[/code]. Multiple file types can also be specified in a single filter. [code]"*.png, *.jpg, *.jpeg ; Supported Images"[/code] will show both PNG and JPEG files when selected. </member> + <member name="option_count" type="int" setter="set_option_count" getter="get_option_count" default="0"> + The number of additional [OptionButton]s and [CheckBox]es in the dialog. + </member> <member name="show_hidden_files" type="bool" setter="set_show_hidden_files" getter="is_showing_hidden_files" default="false"> If [code]true[/code], hidden files and directories will be visible in the [EditorFileDialog]. This property is synchronized with [member EditorSettings.filesystem/file_dialog/show_hidden_files]. </member> diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml index 82ba956151..88a6eeec26 100644 --- a/doc/classes/EditorImportPlugin.xml +++ b/doc/classes/EditorImportPlugin.xml @@ -120,6 +120,13 @@ <link title="Import plugins">$DOCS_URL/tutorials/plugins/editor/import_plugins.html</link> </tutorials> <methods> + <method name="_can_import_threaded" qualifiers="virtual const"> + <return type="bool" /> + <description> + Tells whether this importer can be run in parallel on threads, or, on the contrary, it's only safe for the editor to call it from the main thread, for one file at a time. + If this method is not overridden, it will return [code]true[/code] by default (i.e., safe for parallel importing). + </description> + </method> <method name="_get_import_options" qualifiers="virtual const"> <return type="Dictionary[]" /> <param index="0" name="path" type="String" /> diff --git a/doc/classes/EditorInspector.xml b/doc/classes/EditorInspector.xml index cfdc172fd1..6b25be490e 100644 --- a/doc/classes/EditorInspector.xml +++ b/doc/classes/EditorInspector.xml @@ -28,6 +28,7 @@ </method> </methods> <members> + <member name="follow_focus" type="bool" setter="set_follow_focus" getter="is_following_focus" overrides="ScrollContainer" default="true" /> <member name="horizontal_scroll_mode" type="int" setter="set_horizontal_scroll_mode" getter="get_horizontal_scroll_mode" overrides="ScrollContainer" enum="ScrollContainer.ScrollMode" default="0" /> </members> <signals> diff --git a/doc/classes/EditorInterface.xml b/doc/classes/EditorInterface.xml index d0de09e451..7187617c4c 100644 --- a/doc/classes/EditorInterface.xml +++ b/doc/classes/EditorInterface.xml @@ -87,6 +87,7 @@ <return type="VBoxContainer" /> <description> Returns the editor control responsible for main screen plugins and tools. Use it with plugins that implement [method EditorPlugin._has_main_screen]. + [b]Note:[/b] This node is a [VBoxContainer], which means that if you add a [Control] child to it, you need to set the child's [member Control.size_flags_vertical] to [constant Control.SIZE_EXPAND_FILL] to make it use the full available space. [b]Warning:[/b] Removing and freeing this node will render a part of the editor useless and may cause a crash. </description> </method> @@ -195,6 +196,15 @@ Shows the given property on the given [param object] in the editor's Inspector dock. If [param inspector_only] is [code]true[/code], plugins will not attempt to edit [param object]. </description> </method> + <method name="is_multi_window_enabled" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if multiple window support is enabled in the editor. Multiple window support is enabled if [i]all[/i] of these statements are true: + - [member EditorSettings.interface/multi_window/enable] is [code]true[/code]. + - [member EditorSettings.interface/editor/single_window_mode] is [code]false[/code]. + - [member Viewport.gui_embed_subwindows] is [code]false[/code]. This is forced to [code]true[/code] on platforms that don't support multiple windows such as Web, or when the [code]--single-window[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url] is used. + </description> + </method> <method name="is_playing_scene" qualifiers="const"> <return type="bool" /> <description> @@ -285,6 +295,47 @@ See also [method Window.set_unparent_when_invisible]. </description> </method> + <method name="popup_node_selector"> + <return type="void" /> + <param index="0" name="callback" type="Callable" /> + <param index="1" name="valid_types" type="StringName[]" default="[]" /> + <description> + Pops up an editor dialog for selecting a [Node] from the edited scene. The [param callback] must take a single argument of type [NodePath]. It is called on the selected [NodePath] or the empty path [code]^""[/code] if the dialog is canceled. If [param valid_types] is provided, the dialog will only show Nodes that match one of the listed Node types. + [b]Example:[/b] + [codeblock] + func _ready(): + if Engine.is_editor_hint(): + EditorInterface.popup_node_selector(_on_node_selected, ["Button"]) + + func _on_node_selected(node_path): + if node_path.is_empty(): + print("node selection canceled") + else: + print("selected ", node_path) + [/codeblock] + </description> + </method> + <method name="popup_property_selector"> + <return type="void" /> + <param index="0" name="object" type="Object" /> + <param index="1" name="callback" type="Callable" /> + <param index="2" name="type_filter" type="PackedInt32Array" default="PackedInt32Array()" /> + <description> + Pops up an editor dialog for selecting properties from [param object]. The [param callback] must take a single argument of type [NodePath]. It is called on the selected property path (see [method NodePath.get_as_property_path]) or the empty path [code]^""[/code] if the dialog is canceled. If [param type_filter] is provided, the dialog will only show properties that match one of the listed [enum Variant.Type] values. + [b]Example:[/b] + [codeblock] + func _ready(): + if Engine.is_editor_hint(): + EditorInterface.popup_property_selector(this, _on_property_selected, [TYPE_INT]) + + func _on_property_selected(property_path): + if property_path.is_empty(): + print("property selection canceled") + else: + print("selected ", property_path) + [/codeblock] + </description> + </method> <method name="reload_scene_from_path"> <return type="void" /> <param index="0" name="scene_filepath" type="String" /> diff --git a/doc/classes/EditorNode3DGizmo.xml b/doc/classes/EditorNode3DGizmo.xml index 1680400384..7597489601 100644 --- a/doc/classes/EditorNode3DGizmo.xml +++ b/doc/classes/EditorNode3DGizmo.xml @@ -9,6 +9,13 @@ <tutorials> </tutorials> <methods> + <method name="_begin_handle_action" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="id" type="int" /> + <param index="1" name="secondary" type="bool" /> + <description> + </description> + </method> <method name="_commit_handle" qualifiers="virtual"> <return type="void" /> <param index="0" name="id" type="int" /> diff --git a/doc/classes/EditorNode3DGizmoPlugin.xml b/doc/classes/EditorNode3DGizmoPlugin.xml index da7ee17335..8fd7c167d9 100644 --- a/doc/classes/EditorNode3DGizmoPlugin.xml +++ b/doc/classes/EditorNode3DGizmoPlugin.xml @@ -11,6 +11,14 @@ <link title="Node3D gizmo plugins">$DOCS_URL/tutorials/plugins/editor/3d_gizmos.html</link> </tutorials> <methods> + <method name="_begin_handle_action" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="gizmo" type="EditorNode3DGizmo" /> + <param index="1" name="handle_id" type="int" /> + <param index="2" name="secondary" type="bool" /> + <description> + </description> + </method> <method name="_can_be_hidden" qualifiers="virtual const"> <return type="bool" /> <description> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 50709f9ef5..e874b44cfc 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -239,7 +239,7 @@ <description> Override this method in your plugin to return a [Texture2D] in order to give it an icon. For main screen plugins, this appears at the top of the screen, to the right of the "2D", "3D", "Script", and "AssetLib" buttons. - Ideally, the plugin icon should be white with a transparent background and 16x16 pixels in size. + Ideally, the plugin icon should be white with a transparent background and 16×16 pixels in size. [codeblocks] [gdscript] func _get_plugin_icon(): @@ -327,14 +327,14 @@ <param index="0" name="object" type="Object" /> <description> Implement this function if your plugin edits a specific type of object (Resource or Node). If you return [code]true[/code], then you will get the functions [method _edit] and [method _make_visible] called when the editor requests them. If you have declared the methods [method _forward_canvas_gui_input] and [method _forward_3d_gui_input] these will be called too. - [b]Note:[/b] Each plugin should handle only one type of objects at a time. If a plugin handes more types of objects and they are edited at the same time, it will result in errors. + [b]Note:[/b] Each plugin should handle only one type of objects at a time. If a plugin handles more types of objects and they are edited at the same time, it will result in errors. </description> </method> <method name="_has_main_screen" qualifiers="virtual const"> <return type="bool" /> <description> Returns [code]true[/code] if this is a main screen editor plugin (it goes in the workspace selector together with [b]2D[/b], [b]3D[/b], [b]Script[/b] and [b]AssetLib[/b]). - When the plugin's workspace is selected, other main screen plugins will be hidden, but your plugin will not appear automatically. It needs to be added as a child of [method EditorInterface.get_base_control] and made visible inside [method _make_visible]. + When the plugin's workspace is selected, other main screen plugins will be hidden, but your plugin will not appear automatically. It needs to be added as a child of [method EditorInterface.get_editor_main_screen] and made visible inside [method _make_visible]. Use [method _get_plugin_name] and [method _get_plugin_icon] to customize the plugin button's appearance. [codeblock] var plugin_control @@ -409,8 +409,10 @@ <return type="Button" /> <param index="0" name="control" type="Control" /> <param index="1" name="title" type="String" /> + <param index="2" name="shortcut" type="Shortcut" default="null" /> <description> Adds a control to the bottom panel (together with Output, Debug, Animation, etc). Returns a reference to the button added. It's up to you to hide/show the button when needed. When your plugin is deactivated, make sure to remove your custom control with [method remove_control_from_bottom_panel] and free it with [method Node.queue_free]. + Optionally, you can specify a shortcut parameter. When pressed, this shortcut will toggle the bottom panel's visibility. See the default editor bottom panel shortcuts in the Editor Settings for inspiration. Per convention, they all use [kbd]Alt[/kbd] modifier. </description> </method> <method name="add_control_to_container"> @@ -427,10 +429,12 @@ <return type="void" /> <param index="0" name="slot" type="int" enum="EditorPlugin.DockSlot" /> <param index="1" name="control" type="Control" /> + <param index="2" name="shortcut" type="Shortcut" default="null" /> <description> Adds the control to a specific dock slot (see [enum DockSlot] for options). If the dock is repositioned and as long as the plugin is active, the editor will save the dock position on further sessions. When your plugin is deactivated, make sure to remove your custom control with [method remove_control_from_docks] and free it with [method Node.queue_free]. + Optionally, you can specify a shortcut parameter. When pressed, this shortcut will toggle the dock's visibility once it's moved to the bottom panel (this shortcut does not affect the dock otherwise). See the default editor bottom panel shortcuts in the Editor Settings for inspiration. Per convention, they all use [kbd]Alt[/kbd] modifier. </description> </method> <method name="add_custom_type"> @@ -559,11 +563,10 @@ The callback should have 4 arguments: [Object] [code]undo_redo[/code], [Object] [code]modified_object[/code], [String] [code]property[/code] and [Variant] [code]new_value[/code]. They are, respectively, the [UndoRedo] object used by the inspector, the currently modified object, the name of the modified property and the new value the property is about to take. </description> </method> - <method name="get_editor_interface" is_deprecated="true"> + <method name="get_editor_interface" deprecated="[EditorInterface] is a global singleton and can be accessed directly by its name."> <return type="EditorInterface" /> <description> Returns the [EditorInterface] singleton instance. - [i]Deprecated.[/i] [EditorInterface] is a global singleton and can be accessed directly by its name. </description> </method> <method name="get_export_as_menu"> @@ -750,16 +753,15 @@ Emitted when user changes the workspace ([b]2D[/b], [b]3D[/b], [b]Script[/b], [b]AssetLib[/b]). Also works with custom screens defined by plugins. </description> </signal> - <signal name="project_settings_changed" is_deprecated="true"> + <signal name="project_settings_changed" deprecated="Use [signal ProjectSettings.settings_changed] instead."> <description> Emitted when any project setting has changed. - [i]Deprecated.[/i] Use [signal ProjectSettings.settings_changed] instead. </description> </signal> <signal name="resource_saved"> <param index="0" name="resource" type="Resource" /> <description> - Emitted when the given [param resource] was saved on disc. + Emitted when the given [param resource] was saved on disc. See also [signal scene_saved]. </description> </signal> <signal name="scene_changed"> @@ -771,7 +773,13 @@ <signal name="scene_closed"> <param index="0" name="filepath" type="String" /> <description> - Emitted when user closes a scene. The argument is file path to a closed scene. + Emitted when user closes a scene. The argument is a file path to the closed scene. + </description> + </signal> + <signal name="scene_saved"> + <param index="0" name="filepath" type="String" /> + <description> + Emitted when a scene was saved on disc. The argument is a file path to the saved scene. See also [signal resource_saved]. </description> </signal> </signals> diff --git a/doc/classes/EditorProperty.xml b/doc/classes/EditorProperty.xml index 4fd288f16d..2b1083393f 100644 --- a/doc/classes/EditorProperty.xml +++ b/doc/classes/EditorProperty.xml @@ -84,7 +84,7 @@ <member name="label" type="String" setter="set_label" getter="get_label" default=""""> Set this property to change the label (if you want to show one). </member> - <member name="read_only" type="bool" setter="set_read_only" getter="is_read_only" default="false"> + <member name="read_only" type="bool" setter="set_read_only" getter="is_read_only" default="false" keywords="enabled, disabled, editable"> Used by the inspector, set to [code]true[/code] when the property is read-only. </member> </members> diff --git a/doc/classes/EditorResourcePicker.xml b/doc/classes/EditorResourcePicker.xml index f139502e18..4649e26edf 100644 --- a/doc/classes/EditorResourcePicker.xml +++ b/doc/classes/EditorResourcePicker.xml @@ -43,7 +43,7 @@ <member name="base_type" type="String" setter="set_base_type" getter="get_base_type" default=""""> The base type of allowed resource types. Can be a comma-separated list of several options. </member> - <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true"> + <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true" keywords="readonly, disabled, enabled"> If [code]true[/code], the value can be selected and edited. </member> <member name="edited_resource" type="Resource" setter="set_edited_resource" getter="get_edited_resource"> diff --git a/doc/classes/EditorScript.xml b/doc/classes/EditorScript.xml index 8033c18918..24480437fd 100644 --- a/doc/classes/EditorScript.xml +++ b/doc/classes/EditorScript.xml @@ -48,11 +48,10 @@ [b]Warning:[/b] The implementation of this method is currently disabled. </description> </method> - <method name="get_editor_interface" qualifiers="const" is_deprecated="true"> + <method name="get_editor_interface" qualifiers="const" deprecated="[EditorInterface] is a global singleton and can be accessed directly by its name."> <return type="EditorInterface" /> <description> Returns the [EditorInterface] singleton instance. - [i]Deprecated.[/i] [EditorInterface] is a global singleton and can be accessed directly by its name. </description> </method> <method name="get_scene" qualifiers="const"> diff --git a/doc/classes/EditorSelection.xml b/doc/classes/EditorSelection.xml index 09aae04d04..4ef960ac5c 100644 --- a/doc/classes/EditorSelection.xml +++ b/doc/classes/EditorSelection.xml @@ -27,13 +27,13 @@ <method name="get_selected_nodes"> <return type="Node[]" /> <description> - Gets the list of selected nodes. + Returns the list of selected nodes. </description> </method> <method name="get_transformable_selected_nodes"> <return type="Node[]" /> <description> - Gets the list of selected nodes, optimized for transform operations (i.e. moving them, rotating, etc). This list avoids situations where a node is selected and also child/grandchild. + Returns the list of selected nodes, optimized for transform operations (i.e. moving them, rotating, etc.). This list can be used to avoid situations where a node is selected and is also a child/grandchild. </description> </method> <method name="remove_node"> diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index 6edd8af7cc..573171b7e1 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -185,6 +185,9 @@ <member name="debugger/auto_switch_to_remote_scene_tree" type="bool" setter="" getter=""> If [code]true[/code], automatically switches to the [b]Remote[/b] scene tree when running the project from the editor. If [code]false[/code], stays on the [b]Local[/b] scene tree when running the project from the editor. </member> + <member name="debugger/profile_native_calls" type="bool" setter="" getter=""> + If [code]true[/code], enables collection of profiling data from non-GDScript Godot functions, such as engine class methods. Enabling this slows execution while profiling further. + </member> <member name="debugger/profiler_frame_history_size" type="int" setter="" getter=""> The size of the profiler's frame history. The default value (3600) allows seeing up to 60 seconds of profiling if the project renders at a constant 60 FPS. Higher values allow viewing longer periods of profiling in the graphs, especially when the project is running at high framerates. </member> @@ -217,6 +220,9 @@ <member name="docks/scene_tree/auto_expand_to_selected" type="bool" setter="" getter=""> If [code]true[/code], the scene tree dock will automatically unfold nodes when a node that has folded parents is selected. </member> + <member name="docks/scene_tree/center_node_on_reparent" type="bool" setter="" getter=""> + If [code]true[/code], new node created when reparenting node(s) will be positioned at the average position of the selected node(s). + </member> <member name="docks/scene_tree/start_create_dialog_fully_expanded" type="bool" setter="" getter=""> If [code]true[/code], the Create dialog (Create New Node/Create New Resource) will start with all its sections expanded. Otherwise, sections will be collapsed until the user starts searching (which will automatically expand sections as needed). </member> @@ -259,13 +265,14 @@ The color of the viewport border in the 2D editor. This border represents the viewport's size at the base resolution defined in the Project Settings. Objects placed outside this border will not be visible unless a [Camera2D] node is used, or unless the window is resized and the stretch mode is set to [code]disabled[/code]. </member> <member name="editors/3d/default_fov" type="float" setter="" getter=""> - The default camera field of view to use in the 3D editor (in degrees). The camera field of view can be adjusted on a per-scene basis using the [b]View[/b] menu at the top of the 3D editor. If a scene had its camera field of view adjusted using the [b]View[/b] menu, this setting is ignored in the scene in question. This setting is also ignored while a Camera3D node is being previewed in the editor. + The default camera vertical field of view to use in the 3D editor (in degrees). The camera field of view can be adjusted on a per-scene basis using the [b]View[/b] menu at the top of the 3D editor. If a scene had its camera field of view adjusted using the [b]View[/b] menu, this setting is ignored in the scene in question. This setting is also ignored while a [Camera3D] node is being previewed in the editor. + [b]Note:[/b] The editor camera always uses the [b]Keep Height[/b] aspect mode. </member> <member name="editors/3d/default_z_far" type="float" setter="" getter=""> - The default camera far clip distance to use in the 3D editor (in degrees). Higher values make it possible to view objects placed further away from the camera, at the cost of lower precision in the depth buffer (which can result in visible Z-fighting in the distance). The camera far clip distance can be adjusted on a per-scene basis using the [b]View[/b] menu at the top of the 3D editor. If a scene had its camera far clip distance adjusted using the [b]View[/b] menu, this setting is ignored in the scene in question. This setting is also ignored while a Camera3D node is being previewed in the editor. + The default camera far clip distance to use in the 3D editor (in degrees). Higher values make it possible to view objects placed further away from the camera, at the cost of lower precision in the depth buffer (which can result in visible Z-fighting in the distance). The camera far clip distance can be adjusted on a per-scene basis using the [b]View[/b] menu at the top of the 3D editor. If a scene had its camera far clip distance adjusted using the [b]View[/b] menu, this setting is ignored in the scene in question. This setting is also ignored while a [Camera3D] node is being previewed in the editor. </member> <member name="editors/3d/default_z_near" type="float" setter="" getter=""> - The default camera near clip distance to use in the 3D editor (in degrees). Lower values make it possible to view objects placed closer to the camera, at the cost of lower precision in the depth buffer (which can result in visible Z-fighting in the distance). The camera near clip distance can be adjusted on a per-scene basis using the [b]View[/b] menu at the top of the 3D editor. If a scene had its camera near clip distance adjusted using the [b]View[/b] menu, this setting is ignored in the scene in question. This setting is also ignored while a Camera3D node is being previewed in the editor. + The default camera near clip distance to use in the 3D editor (in degrees). Lower values make it possible to view objects placed closer to the camera, at the cost of lower precision in the depth buffer (which can result in visible Z-fighting in the distance). The camera near clip distance can be adjusted on a per-scene basis using the [b]View[/b] menu at the top of the 3D editor. If a scene had its camera near clip distance adjusted using the [b]View[/b] menu, this setting is ignored in the scene in question. This setting is also ignored while a [Camera3D] node is being previewed in the editor. </member> <member name="editors/3d/freelook/freelook_activation_modifier" type="int" setter="" getter=""> The modifier key to use to enable freelook in the 3D editor (on top of pressing the right mouse button). @@ -422,6 +429,9 @@ <member name="editors/panning/warped_mouse_panning" type="bool" setter="" getter=""> If [code]true[/code], warps the mouse around the 2D viewport while panning in the 2D editor. This makes it possible to pan over a large area without having to exit panning and adjust the mouse cursor. </member> + <member name="editors/polygon_editor/auto_bake_delay" type="float" setter="" getter=""> + The delay in seconds until more complex and performance costly polygon editors commit their outlines, e.g. the 2D navigation polygon editor rebakes the navigation mesh polygons. A negative value stops the auto bake. + </member> <member name="editors/polygon_editor/point_grab_radius" type="int" setter="" getter=""> The radius in which points can be selected in the [Polygon2D] and [CollisionPolygon2D] editors (in pixels). Higher values make it easier to select points quickly, but can make it more difficult to select the expected point when several points are located close to each other. </member> @@ -438,6 +448,69 @@ The color to use for the TileMap editor's grid. [b]Note:[/b] Only effective if [member editors/tiles_editor/display_grid] is [code]true[/code]. </member> + <member name="editors/tiles_editor/highlight_selected_layer" type="bool" setter="" getter=""> + Highlight the currently selected TileMapLayer by dimming the other ones in the scene. + </member> + <member name="editors/visual_editors/category_colors/color_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Color" category. + </member> + <member name="editors/visual_editors/category_colors/conditional_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Conditional" category. + </member> + <member name="editors/visual_editors/category_colors/input_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Input" category. + </member> + <member name="editors/visual_editors/category_colors/output_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Output" category. + </member> + <member name="editors/visual_editors/category_colors/particle_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Particle" category. + </member> + <member name="editors/visual_editors/category_colors/scalar_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Scalar" category. + </member> + <member name="editors/visual_editors/category_colors/special_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Special" category. + </member> + <member name="editors/visual_editors/category_colors/textures_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Textures" category. + </member> + <member name="editors/visual_editors/category_colors/transform_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Transform" category. + </member> + <member name="editors/visual_editors/category_colors/utility_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Utility" category. + </member> + <member name="editors/visual_editors/category_colors/vector_color" type="Color" setter="" getter=""> + The color of a graph node's header when it belongs to the "Vector" category. + </member> + <member name="editors/visual_editors/color_theme" type="String" setter="" getter=""> + The color theme to use in the visual shader editor. + </member> + <member name="editors/visual_editors/connection_colors/boolean_color" type="Color" setter="" getter=""> + The color of a port/connection of boolean type. + </member> + <member name="editors/visual_editors/connection_colors/sampler_color" type="Color" setter="" getter=""> + The color of a port/connection of sampler type. + </member> + <member name="editors/visual_editors/connection_colors/scalar_color" type="Color" setter="" getter=""> + The color of a port/connection of scalar type (float, int, unsigned int). + </member> + <member name="editors/visual_editors/connection_colors/transform_color" type="Color" setter="" getter=""> + The color of a port/connection of transform type. + </member> + <member name="editors/visual_editors/connection_colors/vector2_color" type="Color" setter="" getter=""> + The color of a port/connection of Vector2 type. + </member> + <member name="editors/visual_editors/connection_colors/vector3_color" type="Color" setter="" getter=""> + The color of a port/connection of Vector3 type. + </member> + <member name="editors/visual_editors/connection_colors/vector4_color" type="Color" setter="" getter=""> + The color of a port/connection of Vector4 type. + </member> + <member name="editors/visual_editors/grid_pattern" type="int" setter="" getter=""> + The pattern used for the background grid. + </member> <member name="editors/visual_editors/lines_curvature" type="float" setter="" getter=""> The curvature to use for connection lines in the visual shader editor. Higher values will make connection lines appear more curved, with values above [code]0.5[/code] resulting in more "angular" turns in the middle of connection lines. </member> @@ -463,6 +536,21 @@ <member name="filesystem/external_programs/raster_image_editor" type="String" setter="" getter=""> The program that opens raster image files when clicking "Open in External Program" option in Filesystem Dock. If not specified, the file will be opened in the system's default program. </member> + <member name="filesystem/external_programs/terminal_emulator" type="String" setter="" getter=""> + The terminal emulator program to use when using [b]Open in Terminal[/b] context menu action in the FileSystem dock. You can enter an absolute path to a program binary, or a path to a program that is present in the [code]PATH[/code] environment variable. + If left empty, Godot will use the default terminal emulator for the system: + - [b]Windows:[/b] PowerShell + - [b]macOS:[/b] Terminal.app + - [b]Linux:[/b] The first terminal found on the system in this order: gnome-terminal, konsole, xfce4-terminal, lxterminal, kitty, alacritty, urxvt, xterm. + To use Command Prompt (cmd) instead of PowerShell on Windows, enter [code]cmd[/code] in this field and the correct flags will automatically be used. + On macOS, make sure to point to the actual program binary located within the [code]Programs/MacOS[/code] folder of the .app bundle, rather than the .app bundle directory. + If specifying a custom terminal emulator, you may need to override [member filesystem/external_programs/terminal_emulator_flags] so it opens in the correct folder. + </member> + <member name="filesystem/external_programs/terminal_emulator_flags" type="String" setter="" getter=""> + The command-line arguments to pass to the terminal emulator that is run when using [b]Open in Terminal[/b] context menu action in the FileSystem dock. See also [member filesystem/external_programs/terminal_emulator]. + If left empty, the default flags are [code]{directory}[/code], which is replaced by the absolute path to the directory that is being opened in the terminal. + [b]Note:[/b] If the terminal emulator is set to PowerShell, cmd, or Konsole, Godot will automatically prepend arguments to this list, as these terminals require nonstandard arguments to open in the correct folder. + </member> <member name="filesystem/external_programs/vector_image_editor" type="String" setter="" getter=""> The program that opens vector image files when clicking "Open in External Program" option in Filesystem Dock. If not specified, the file will be opened in the system's default program. </member> @@ -477,7 +565,7 @@ <member name="filesystem/file_dialog/thumbnail_size" type="int" setter="" getter=""> The thumbnail size to use in the editor's file dialogs (in pixels). See also [member docks/filesystem/thumbnail_size]. </member> - <member name="filesystem/import/blender/blender3_path" type="String" setter="" getter=""> + <member name="filesystem/import/blender/blender_path" type="String" setter="" getter=""> The path to the directory containing the Blender executable used for converting the Blender 3D scene files [code].blend[/code] to glTF 2.0 format during import. Blender 3.0 or later is required. To enable this feature for your specific project, use [member ProjectSettings.filesystem/import/blender/enabled]. </member> @@ -489,9 +577,9 @@ The maximum idle uptime (in seconds) of the Blender process. This prevents Godot from having to create a new process for each import within the given seconds. </member> - <member name="filesystem/import/fbx/fbx2gltf_path" type="String" setter="" getter=""> + <member name="filesystem/import/fbx2gltf/fbx2gltf_path" type="String" setter="" getter=""> The path to the FBX2glTF executable used for converting Autodesk FBX 3D scene files [code].fbx[/code] to glTF 2.0 format during import. - To enable this feature for your specific project, use [member ProjectSettings.filesystem/import/fbx/enabled]. + To enable this feature for your specific project, use [member ProjectSettings.filesystem/import/fbx2gltf/enabled]. </member> <member name="filesystem/on_save/compress_binary_resources" type="bool" setter="" getter=""> If [code]true[/code], uses lossless compression for binary resources. @@ -568,8 +656,13 @@ <member name="interface/editor/font_subpixel_positioning" type="int" setter="" getter=""> The subpixel positioning mode to use when rendering editor font glyphs. This affects both the main and code fonts. [b]Disabled[/b] is the fastest to render and uses the least memory. [b]Auto[/b] only uses subpixel positioning for small font sizes (where the benefit is the most noticeable). [b]One Half of a Pixel[/b] and [b]One Quarter of a Pixel[/b] force the same subpixel positioning mode for all editor fonts, regardless of their size (with [b]One Quarter of a Pixel[/b] being the highest-quality option). </member> - <member name="interface/editor/low_processor_mode_sleep_usec" type="float" setter="" getter=""> + <member name="interface/editor/localize_settings" type="bool" setter="" getter=""> + If [code]true[/code], setting names in the editor are localized when possible. + [b]Note:[/b] This setting affects most [EditorInspector]s in the editor UI, primarily Project Settings and Editor Settings. To control names displayed in the Inspector dock, use [member interface/inspector/default_property_name_style] instead. + </member> + <member name="interface/editor/low_processor_mode_sleep_usec" type="int" setter="" getter=""> The amount of sleeping between frames when the low-processor usage mode is enabled (in microseconds). Higher values will result in lower CPU/GPU usage, which can improve battery life on laptops. However, higher values will result in a less responsive editor. The default value is set to allow for maximum smoothness on monitors up to 144 Hz. See also [member interface/editor/unfocused_low_processor_mode_sleep_usec]. + [b]Note:[/b] This setting is ignored if [member interface/editor/update_continuously] is [code]true[/code], as enabling that setting disables low-processor mode. </member> <member name="interface/editor/main_font" type="String" setter="" getter=""> The font to use for the editor interface. Must be a resource of a [Font] type such as a [code].ttf[/code] or [code].otf[/code] font file. @@ -589,35 +682,96 @@ <member name="interface/editor/save_each_scene_on_quit" type="bool" setter="" getter=""> If [code]false[/code], the editor will save all scenes when confirming the [b]Save[/b] action when quitting the editor or quitting to the project list. If [code]true[/code], the editor will ask to save each scene individually. </member> + <member name="interface/editor/save_on_focus_loss" type="bool" setter="" getter=""> + If [code]true[/code], scenes and scripts are saved when the editor loses focus. Depending on the work flow, this behavior can be less intrusive than [member text_editor/behavior/files/autosave_interval_secs] or remembering to save manually. + </member> <member name="interface/editor/separate_distraction_mode" type="bool" setter="" getter=""> If [code]true[/code], the editor's Script tab will have a separate distraction mode setting from the 2D/3D/AssetLib tabs. If [code]false[/code], the distraction-free mode toggle is shared between all tabs. </member> <member name="interface/editor/show_internal_errors_in_toast_notifications" type="int" setter="" getter=""> If enabled, displays internal engine errors in toast notifications (toggleable by clicking the "bell" icon at the bottom of the editor). No matter the value of this setting, non-internal engine errors will always be visible in toast notifications. - The default [b]Auto[/b] value will only enable this if the editor was compiled with the [code]dev=yes[/code] option (the default is [code]dev=no[/code]). + The default [b]Auto[/b] value will only enable this if the editor was compiled with the [code]dev_build=yes[/code] SCons option (the default is [code]dev_build=no[/code]). + </member> + <member name="interface/editor/show_update_spinner" type="int" setter="" getter=""> + If enabled, displays an icon in the top-right corner of the editor that spins when the editor redraws a frame. This can be used to diagnose situations where the engine is constantly redrawing, which should be avoided as this increases CPU and GPU utilization for no good reason. To further troubleshoot these situations, start the editor with the [code]--debug-canvas-item-redraw[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. + Consider enabling this if you are developing editor plugins to ensure they only make the editor redraw when required. + The default [b]Auto[/b] value will only enable this if the editor was compiled with the [code]dev_build=yes[/code] SCons option (the default is [code]dev_build=no[/code]). + [b]Note:[/b] If [member interface/editor/update_continuously] is [code]true[/code], the spinner icon displays in red. </member> <member name="interface/editor/single_window_mode" type="bool" setter="" getter=""> If [code]true[/code], embed modal windows such as docks inside the main editor window. When single-window mode is enabled, tooltips will also be embedded inside the main editor window, which means they can't be displayed outside of the editor window. + [b]Note:[/b] To query whether the editor can use multiple windows in an editor plugin, use [method EditorInterface.is_multi_window_enabled] instead of querying the value of this editor setting. + </member> + <member name="interface/editor/ui_layout_direction" type="int" setter="" getter=""> + Editor UI default layout direction. </member> - <member name="interface/editor/unfocused_low_processor_mode_sleep_usec" type="float" setter="" getter=""> + <member name="interface/editor/unfocused_low_processor_mode_sleep_usec" type="int" setter="" getter=""> When the editor window is unfocused, the amount of sleeping between frames when the low-processor usage mode is enabled (in microseconds). Higher values will result in lower CPU/GPU usage, which can improve battery life on laptops (in addition to improving the running project's performance if the editor has to redraw continuously). However, higher values will result in a less responsive editor. The default value is set to limit the editor to 20 FPS when the editor window is unfocused. See also [member interface/editor/low_processor_mode_sleep_usec]. + [b]Note:[/b] This setting is ignored if [member interface/editor/update_continuously] is [code]true[/code], as enabling that setting disables low-processor mode. + </member> + <member name="interface/editor/update_continuously" type="bool" setter="" getter=""> + If [code]true[/code], redraws the editor every frame even if nothing has changed on screen. When this setting is enabled, the update spinner displays in red (see [member interface/editor/show_update_spinner]). + [b]Warning:[/b] This greatly increases CPU and GPU utilization, leading to increased power usage. This should only be enabled for troubleshooting purposes. </member> <member name="interface/editor/use_embedded_menu" type="bool" setter="" getter=""> If [code]true[/code], editor main menu is using embedded [MenuBar] instead of system global menu. Specific to the macOS platform. </member> + <member name="interface/editor/use_native_file_dialogs" type="bool" setter="" getter=""> + If [code]true[/code], editor UI uses OS native file/directory selection dialogs. + </member> + <member name="interface/editor/vsync_mode" type="int" setter="" getter=""> + Sets the V-Sync mode for the editor. Does not affect the project when run from the editor (this is controlled by [member ProjectSettings.display/window/vsync/vsync_mode]). + Depending on the platform and used renderer, the engine will fall back to [b]Enabled[/b] if the desired mode is not supported. + [b]Note:[/b] V-Sync modes other than [b]Enabled[/b] are only supported in the Forward+ and Mobile rendering methods, not Compatibility. + </member> + <member name="interface/inspector/auto_unfold_foreign_scenes" type="bool" setter="" getter=""> + If [code]true[/code], automatically expands property groups in the Inspector dock when opening a scene that hasn't been opened previously. If [code]false[/code], all groups remain collapsed by default. + </member> + <member name="interface/inspector/default_color_picker_mode" type="int" setter="" getter=""> + The default color picker mode to use when opening [ColorPicker]s in the editor. This mode can be temporarily adjusted on the color picker itself. + </member> + <member name="interface/inspector/default_color_picker_shape" type="int" setter="" getter=""> + The default color picker shape to use when opening [ColorPicker]s in the editor. This shape can be temporarily adjusted on the color picker itself. + </member> + <member name="interface/inspector/default_float_step" type="float" setter="" getter=""> + The floating-point precision to use for properties that don't define an explicit precision step. Lower values allow entering more precise values. + </member> + <member name="interface/inspector/default_property_name_style" type="int" setter="" getter=""> + The default property name style to display in the Inspector dock. This style can be temporarily adjusted in the Inspector dock's menu. + - [b]Raw:[/b] Displays properties in [code]snake_case[/code]. + - [b]Capitalized:[/b] Displays properties capitalized. + - [b]Localized:[/b] Displays the localized string for the current editor language if a translation is available for the given property. If no translation is available, falls back to [b]Capitalized[/b]. + [b]Note:[/b] To display translated setting names in Project Settings and Editor Settings, use [member interface/editor/localize_settings] instead. + </member> + <member name="interface/inspector/disable_folding" type="bool" setter="" getter=""> + If [code]true[/code], forces all property groups to be expanded in the Inspector dock and prevents collapsing them. + </member> <member name="interface/inspector/float_drag_speed" type="float" setter="" getter=""> Base speed for increasing/decreasing float values by dragging them in the inspector. </member> + <member name="interface/inspector/horizontal_vector2_editing" type="bool" setter="" getter=""> + If [code]true[/code], [Vector2] and [Vector2i] properties are shown on a single line in the inspector instead of two lines. This is overall more compact, but it can be harder to view and edit large values without expanding the inspector horizontally. + </member> + <member name="interface/inspector/horizontal_vector_types_editing" type="bool" setter="" getter=""> + If [code]true[/code], [Vector3], [Vector3i], [Vector4], [Vector4i], [Rect2], [Rect2i], [Plane], and [Quaternion] properties are shown on a single line in the inspector instead of multiple lines. This is overall more compact, but it can be harder to view and edit large values without expanding the inspector horizontally. + </member> <member name="interface/inspector/max_array_dictionary_items_per_page" type="int" setter="" getter=""> The number of [Array] or [Dictionary] items to display on each "page" in the inspector. Higher values allow viewing more values per page, but take more time to load. This increased load time is noticeable when selecting nodes that have array or dictionary properties in the editor. </member> + <member name="interface/inspector/open_resources_in_current_inspector" type="bool" setter="" getter=""> + If [code]true[/code], subresources can be edited in the current inspector view. If the resource type is defined in [member interface/inspector/resources_to_open_in_new_inspector] or if this setting is [code]false[/code], attempting to edit a subresource always opens a new inspector view. + </member> + <member name="interface/inspector/resources_to_open_in_new_inspector" type="PackedStringArray" setter="" getter=""> + List of resources that should always be opened in a new inspector view, even if [member interface/inspector/open_resources_in_current_inspector] is [code]true[/code]. + </member> <member name="interface/inspector/show_low_level_opentype_features" type="bool" setter="" getter=""> If [code]true[/code], display OpenType features marked as [code]hidden[/code] by the font file in the [Font] editor. </member> <member name="interface/multi_window/enable" type="bool" setter="" getter=""> - If [code]true[/code], the multi window support in editor is enabled. The following panels can become dedicated windows (made floating): Docks, Script editor, and Shader editor. + If [code]true[/code], multiple window support in editor is enabled. The following panels can become dedicated windows (i.e. made floating): Docks, Script editor, and Shader editor. [b]Note:[/b] When [member interface/editor/single_window_mode] is [code]true[/code], the multi window support is always disabled. + [b]Note:[/b] To query whether the editor can use multiple windows in an editor plugin, use [method EditorInterface.is_multi_window_enabled] instead of querying the value of this editor setting. </member> <member name="interface/multi_window/maximize_window" type="bool" setter="" getter=""> If [code]true[/code], when panels are made floating they will be maximized. @@ -632,6 +786,10 @@ <member name="interface/scene_tabs/maximum_width" type="int" setter="" getter=""> The maximum width of each scene tab at the top editor (in pixels). </member> + <member name="interface/scene_tabs/restore_scenes_on_load" type="bool" setter="" getter=""> + If [code]true[/code], when a project is loaded, restores scenes that were opened on the last editor session. + [b]Note:[/b] With many opened scenes, the editor may take longer to become usable. If starting the editor quickly is necessary, consider setting this to [code]false[/code]. + </member> <member name="interface/scene_tabs/show_script_button" type="bool" setter="" getter=""> If [code]true[/code], show a button next to each scene tab that opens the scene's "dominant" script when clicked. The "dominant" script is the one that is at the highest level in the scene's hierarchy. </member> @@ -641,12 +799,16 @@ <member name="interface/theme/accent_color" type="Color" setter="" getter=""> The color to use for "highlighted" user interface elements in the editor (pressed and hovered items). </member> - <member name="interface/theme/additional_spacing" type="float" setter="" getter=""> - The spacing to add for buttons and list items in the editor (in pixels). Increasing this value is useful to improve usability on touch screens, at the cost of reducing the amount of usable screen real estate. + <member name="interface/theme/additional_spacing" type="int" setter="" getter=""> + The extra spacing to add to various GUI elements in the editor (in pixels). Increasing this value is useful to improve usability on touch screens, at the cost of reducing the amount of usable screen real estate. + See also [member interface/theme/spacing_preset]. </member> <member name="interface/theme/base_color" type="Color" setter="" getter=""> The base color to use for user interface elements in the editor. Secondary colors (such as darker/lighter variants) are derived from this color. </member> + <member name="interface/theme/base_spacing" type="int" setter="" getter=""> + The base spacing used by various GUI elements in the editor (in pixels). See also [member interface/theme/spacing_preset]. + </member> <member name="interface/theme/border_size" type="int" setter="" getter=""> The border size to use for interface elements (in pixels). </member> @@ -662,11 +824,14 @@ <member name="interface/theme/draw_extra_borders" type="bool" setter="" getter=""> If [code]true[/code], draws additional borders around interactive UI elements in the editor. This is automatically enabled when using the [b]Black (OLED)[/b] theme preset, as this theme preset uses a fully black background. </member> + <member name="interface/theme/follow_system_theme" type="bool" setter="" getter=""> + If [code]true[/code], the editor theme preset will attempt to automatically match the system theme. + </member> <member name="interface/theme/icon_and_font_color" type="int" setter="" getter=""> The icon and font color scheme to use in the editor. - [b]Auto[/b] determines the color scheme to use automatically based on [member interface/theme/base_color]. - - [b]Dark[/b] makes fonts and icons light (suitable for dark themes). - - [b]Light[/b] makes fonts and icons dark (suitable for light themes). Icon colors are automatically converted by the editor following [url=https://github.com/godotengine/godot/blob/master/editor/editor_themes.cpp#L135]this set of rules[/url]. + - [b]Dark[/b] makes fonts and icons dark (suitable for light themes). Icon colors are automatically converted by the editor following the set of rules defined in [url=https://github.com/godotengine/godot/blob/master/editor/editor_themes.cpp]this file[/url]. + - [b]Light[/b] makes fonts and icons light (suitable for dark themes). </member> <member name="interface/theme/icon_saturation" type="float" setter="" getter=""> The saturation to use for editor icons. Higher values result in more vibrant colors. @@ -678,6 +843,13 @@ <member name="interface/theme/relationship_line_opacity" type="float" setter="" getter=""> The opacity to use when drawing relationship lines in the editor's [Tree]-based GUIs (such as the Scene tree dock). </member> + <member name="interface/theme/spacing_preset" type="String" setter="" getter=""> + The editor theme spacing preset to use. See also [member interface/theme/base_spacing] and [member interface/theme/additional_spacing]. + </member> + <member name="interface/theme/use_system_accent_color" type="bool" setter="" getter=""> + If [code]true[/code], set accent color based on system settings. + [b]Note:[/b] This setting is only effective on Windows and MacOS. + </member> <member name="interface/touchscreen/enable_long_press_as_right_click" type="bool" setter="" getter=""> If [code]true[/code], long press on touchscreen is treated as right click. [b]Note:[/b] Defaults to [code]true[/code] on touchscreen devices. @@ -694,6 +866,9 @@ Specify the multiplier to apply to the scale for the editor gizmo handles to improve usability on touchscreen devices. [b]Note:[/b] Defaults to [code]1[/code] on non-touchscreen devices. </member> + <member name="network/connection/network_mode" type="int" setter="" getter=""> + Determines whether online features are enabled in the editor, such as the Asset Library. Setting this property to "Offline" is recommended to limit editor's internet activity, especially if privacy is a concern. + </member> <member name="network/debug/remote_host" type="String" setter="" getter=""> The address to listen to when starting the remote debugger. This can be set to [code]0.0.0.0[/code] to allow external clients to connect to the remote debugger (instead of restricting the remote debugger to connections from [code]localhost[/code]). </member> @@ -714,6 +889,9 @@ <member name="project_manager/default_renderer" type="String" setter="" getter=""> The renderer type that will be checked off by default when creating a new project. Accepted strings are "forward_plus", "mobile" or "gl_compatibility". </member> + <member name="project_manager/directory_naming_convention" type="int" setter="" getter=""> + Directory naming convention for the project manager. Options are "No convention" (project name is directory name), "kebab-case" (default), "snake_case", "camelCase", "PascalCase", or "Title Case". + </member> <member name="project_manager/sorting_order" type="int" setter="" getter=""> The sorting order to use in the project manager. When changing the sorting order in the project manager, this setting is set permanently in the editor settings. </member> @@ -732,6 +910,9 @@ <member name="run/output/font_size" type="int" setter="" getter=""> The size of the font in the [b]Output[/b] panel at the bottom of the editor. This setting does not impact the font size of the script editor (see [member interface/editor/code_font_size]). </member> + <member name="run/platforms/linuxbsd/prefer_wayland" type="bool" setter="" getter=""> + If [code]true[/code], on Linux/BSD, the editor will check for Wayland first instead of X11 (if available). + </member> <member name="run/window_placement/android_window" type="int" setter="" getter=""> The Android window to display the project on when starting the project from the editor. [b]Note:[/b] Only available in the Android editor. @@ -823,6 +1004,9 @@ <member name="text_editor/behavior/indent/auto_indent" type="bool" setter="" getter=""> If [code]true[/code], automatically indents code when pressing the [kbd]Enter[/kbd] key based on blocks above the new line. </member> + <member name="text_editor/behavior/indent/indent_wrapped_lines" type="bool" setter="" getter=""> + If [code]true[/code], all wrapped lines are indented to the same amount as the unwrapped line. + </member> <member name="text_editor/behavior/indent/size" type="int" setter="" getter=""> When using tab indentation, determines the length of each tab. When using space indentation, determines how many spaces are inserted when pressing [kbd]Tab[/kbd] and when automatic indentation is performed. </member> @@ -836,6 +1020,9 @@ <member name="text_editor/behavior/navigation/move_caret_on_right_click" type="bool" setter="" getter=""> If [code]true[/code], the caret will be moved when right-clicking somewhere in the script editor (like when left-clicking or middle-clicking). If [code]false[/code], the caret will only be moved when left-clicking or middle-clicking somewhere. </member> + <member name="text_editor/behavior/navigation/open_script_when_connecting_signal_to_existing_method" type="bool" setter="" getter=""> + If [code]true[/code], opens the script editor when connecting a signal to an existing script method from the Node dock. + </member> <member name="text_editor/behavior/navigation/scroll_past_end_of_file" type="bool" setter="" getter=""> If [code]true[/code], allows scrolling past the end of the file. </member> @@ -850,8 +1037,14 @@ The number of pixels to scroll with every mouse wheel increment. Higher values make the script scroll by faster when using the mouse wheel. [b]Note:[/b] You can hold down [kbd]Alt[/kbd] while using the mouse wheel to temporarily scroll 5 times faster. </member> + <member name="text_editor/completion/add_node_path_literals" type="bool" setter="" getter=""> + If [code]true[/code], uses [NodePath] instead of [String] when appropriate for code autocompletion or for drag and dropping object properties into the script editor. + </member> + <member name="text_editor/completion/add_string_name_literals" type="bool" setter="" getter=""> + If [code]true[/code], uses [StringName] instead of [String] when appropriate for code autocompletion. + </member> <member name="text_editor/completion/add_type_hints" type="bool" setter="" getter=""> - If [code]true[/code], adds static typing hints such as [code]-> void[/code] and [code]: int[/code] when using code autocompletion or when creating onready variables by drag and dropping nodes into the script editor while pressing the [kbd]Ctrl[/kbd] key. + If [code]true[/code], adds [url=$DOCS_URL/tutorials/scripting/gdscript/static_typing.html]GDScript static typing[/url] hints such as [code]-> void[/code] and [code]: int[/code] when using code autocompletion or when creating onready variables by drag and dropping nodes into the script editor while pressing the [kbd]Ctrl[/kbd] key. If [code]true[/code], newly created scripts will also automatically have type hints added to their method parameters and return types. </member> <member name="text_editor/completion/auto_brace_complete" type="bool" setter="" getter=""> If [code]true[/code], automatically completes braces when making use of code completion. diff --git a/doc/classes/EditorSpinSlider.xml b/doc/classes/EditorSpinSlider.xml index 7108f873e6..783f1243e2 100644 --- a/doc/classes/EditorSpinSlider.xml +++ b/doc/classes/EditorSpinSlider.xml @@ -20,7 +20,7 @@ <member name="label" type="String" setter="set_label" getter="get_label" default=""""> The text that displays to the left of the value. </member> - <member name="read_only" type="bool" setter="set_read_only" getter="is_read_only" default="false"> + <member name="read_only" type="bool" setter="set_read_only" getter="is_read_only" default="false" keywords="enabled, disabled, editable"> If [code]true[/code], the slider can't be interacted with. </member> <member name="size_flags_vertical" type="int" setter="set_v_size_flags" getter="get_v_size_flags" overrides="Control" enum="Control.SizeFlags" is_bitfield="true" default="1" /> diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml index 207cd0bccc..ca78054875 100644 --- a/doc/classes/Engine.xml +++ b/doc/classes/Engine.xml @@ -4,7 +4,7 @@ Provides access to engine properties. </brief_description> <description> - The [Engine] singleton allows you to query and modify the project's run-time parameters, such as frames per second, time scale, and others. + The [Engine] singleton allows you to query and modify the project's run-time parameters, such as frames per second, time scale, and others. It also stores information about the current build of Godot, such as the current version. </description> <tutorials> </tutorials> @@ -12,8 +12,8 @@ <method name="get_architecture_name" qualifiers="const"> <return type="String" /> <description> - Returns the name of the CPU architecture the Godot binary was built for. Possible return values are [code]x86_64[/code], [code]x86_32[/code], [code]arm64[/code], [code]arm32[/code], [code]rv64[/code], [code]riscv[/code], [code]ppc64[/code], [code]ppc[/code], [code]wasm64[/code] and [code]wasm32[/code]. - To detect whether the current CPU architecture is 64-bit, you can use the fact that all 64-bit architecture names have [code]64[/code] in their name: + Returns the name of the CPU architecture the Godot binary was built for. Possible return values include [code]"x86_64"[/code], [code]"x86_32"[/code], [code]"arm64"[/code], [code]"arm32"[/code], [code]"rv64"[/code], [code]"riscv"[/code], [code]"ppc64"[/code], [code]"ppc"[/code], [code]"wasm64"[/code], and [code]"wasm32"[/code]. + To detect whether the current build is 64-bit, you can use the fact that all 64-bit architecture names contain [code]64[/code] in their name: [codeblocks] [gdscript] if "64" in Engine.get_architecture_name(): @@ -28,74 +28,74 @@ GD.Print("Running a 32-bit build of Godot."); [/csharp] [/codeblocks] - [b]Note:[/b] [method get_architecture_name] does [i]not[/i] return the name of the host CPU architecture. For example, if running an x86_32 Godot binary on a x86_64 system, the returned value will be [code]x86_32[/code]. + [b]Note:[/b] This method does [i]not[/i] return the name of the system's CPU architecture (like [method OS.get_processor_name]). For example, when running an [code]x86_32[/code] Godot binary on an [code]x86_64[/code] system, the returned value will still be [code]"x86_32"[/code]. </description> </method> <method name="get_author_info" qualifiers="const"> <return type="Dictionary" /> <description> - Returns engine author information in a Dictionary. - [code]lead_developers[/code] - Array of Strings, lead developer names - [code]founders[/code] - Array of Strings, founder names - [code]project_managers[/code] - Array of Strings, project manager names - [code]developers[/code] - Array of Strings, developer names + Returns the engine author information as a [Dictionary], where each entry is an [Array] of strings with the names of notable contributors to the Godot Engine: [code]lead_developers[/code], [code]founders[/code], [code]project_managers[/code], and [code]developers[/code]. </description> </method> <method name="get_copyright_info" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns an Array of copyright information Dictionaries. - [code]name[/code] - String, component name - [code]parts[/code] - Array of Dictionaries {[code]files[/code], [code]copyright[/code], [code]license[/code]} describing subsections of the component + Returns an [Array] of dictionaries with copyright information for every component of Godot's source code. + Every [Dictionary] contains a [code]name[/code] identifier, and a [code]parts[/code] array of dictionaries. It describes the component in detail with the following entries: + - [code]files[/code] - [Array] of file paths from the source code affected by this component; + - [code]copyright[/code] - [Array] of owners of this component; + - [code]license[/code] - The license applied to this component (such as "[url=https://en.wikipedia.org/wiki/MIT_License#Ambiguity_and_variants]Expat[/url]" or "[url=https://creativecommons.org/licenses/by/4.0/]CC-BY-4.0[/url]"). </description> </method> <method name="get_donor_info" qualifiers="const"> <return type="Dictionary" /> <description> - Returns a Dictionary of Arrays of donor names. + Returns a [Dictionary] of categorized donor names. Each entry is an [Array] of strings: {[code]platinum_sponsors[/code], [code]gold_sponsors[/code], [code]silver_sponsors[/code], [code]bronze_sponsors[/code], [code]mini_sponsors[/code], [code]gold_donors[/code], [code]silver_donors[/code], [code]bronze_donors[/code]} </description> </method> <method name="get_frames_drawn"> <return type="int" /> <description> - Returns the total number of frames drawn. On headless platforms, or if the render loop is disabled with [code]--disable-render-loop[/code] via command line, [method get_frames_drawn] always returns [code]0[/code]. See [method get_process_frames]. + Returns the total number of frames drawn since the engine started. + [b]Note:[/b] On headless platforms, or if rendering is disabled with [code]--disable-render-loop[/code] via command line, this method always returns [code]0[/code]. See also [method get_process_frames]. </description> </method> <method name="get_frames_per_second" qualifiers="const"> <return type="float" /> <description> - Returns the frames per second of the running game. + Returns the average frames rendered every second (FPS), also known as the framerate. </description> </method> <method name="get_license_info" qualifiers="const"> <return type="Dictionary" /> <description> - Returns Dictionary of licenses used by Godot and included third party components. + Returns a [Dictionary] of licenses used by Godot and included third party components. Each entry is a license name (such as "[url=https://en.wikipedia.org/wiki/MIT_License#Ambiguity_and_variants]Expat[/url]") and its associated text. </description> </method> <method name="get_license_text" qualifiers="const"> <return type="String" /> <description> - Returns Godot license text. + Returns the full Godot license text. </description> </method> <method name="get_main_loop" qualifiers="const"> <return type="MainLoop" /> <description> - Returns the main loop object (see [MainLoop] and [SceneTree]). + Returns the instance of the [MainLoop]. This is usually the main [SceneTree] and is the same as [method Node.get_tree]. + [b]Note:[/b] The type instantiated as the main loop can changed with [member ProjectSettings.application/run/main_loop_type]. </description> </method> <method name="get_physics_frames" qualifiers="const"> <return type="int" /> <description> - Returns the total number of frames passed since engine initialization which is advanced on each [b]physics frame[/b]. See also [method get_process_frames]. - [method get_physics_frames] can be used to run expensive logic less often without relying on a [Timer]: + Returns the total number of frames passed since the engine started. This number is increased every [b]physics frame[/b]. See also [method get_process_frames]. + This method can be used to run expensive logic less often without relying on a [Timer]: [codeblocks] [gdscript] func _physics_process(_delta): if Engine.get_physics_frames() % 2 == 0: - pass # Run expensive logic only once every 2 physics frames here. + pass # Run expensive logic only once every 2 physics frames here. [/gdscript] [csharp] public override void _PhysicsProcess(double delta) @@ -120,22 +120,22 @@ <method name="get_process_frames" qualifiers="const"> <return type="int" /> <description> - Returns the total number of frames passed since engine initialization which is advanced on each [b]process frame[/b], regardless of whether the render loop is enabled. See also [method get_frames_drawn] and [method get_physics_frames]. - [method get_process_frames] can be used to run expensive logic less often without relying on a [Timer]: + Returns the total number of frames passed since the engine started. This number is increased every [b]process frame[/b], regardless of whether the render loop is enabled. See also [method get_frames_drawn] and [method get_physics_frames]. + This method can be used to run expensive logic less often without relying on a [Timer]: [codeblocks] [gdscript] func _process(_delta): - if Engine.get_process_frames() % 2 == 0: - pass # Run expensive logic only once every 2 process (render) frames here. + if Engine.get_process_frames() % 5 == 0: + pass # Run expensive logic only once every 5 process (render) frames here. [/gdscript] [csharp] public override void _Process(double delta) { base._Process(delta); - if (Engine.GetProcessFrames() % 2 == 0) + if (Engine.GetProcessFrames() % 5 == 0) { - // Run expensive logic only once every 2 physics frames here. + // Run expensive logic only once every 5 process (render) frames here. } } [/csharp] @@ -146,7 +146,7 @@ <return type="ScriptLanguage" /> <param index="0" name="index" type="int" /> <description> - Returns an instance of a [ScriptLanguage] with the given index. + Returns an instance of a [ScriptLanguage] with the given [param index]. </description> </method> <method name="get_script_language_count"> @@ -159,44 +159,46 @@ <return type="Object" /> <param index="0" name="name" type="StringName" /> <description> - Returns a global singleton with given [param name]. Often used for plugins, e.g. GodotPayments. + Returns the global singleton with the given [param name], or [code]null[/code] if it does not exist. Often used for plugins. See also [method has_singleton] and [method get_singleton_list]. + [b]Note:[/b] Global singletons are not the same as autoloaded nodes, which are configurable in the project settings. </description> </method> <method name="get_singleton_list" qualifiers="const"> <return type="PackedStringArray" /> <description> - Returns a list of available global singletons. + Returns a list of names of all available global singletons. See also [method get_singleton]. </description> </method> <method name="get_version_info" qualifiers="const"> <return type="Dictionary" /> <description> - Returns the current engine version information in a Dictionary. - [code]major[/code] - Holds the major version number as an int - [code]minor[/code] - Holds the minor version number as an int - [code]patch[/code] - Holds the patch version number as an int - [code]hex[/code] - Holds the full version number encoded as a hexadecimal int with one byte (2 places) per number (see example below) - [code]status[/code] - Holds the status (e.g. "beta", "rc1", "rc2", ... "stable") as a String - [code]build[/code] - Holds the build name (e.g. "custom_build") as a String - [code]hash[/code] - Holds the full Git commit hash as a String - [code]year[/code] - Holds the year the version was released in as an int - [code]string[/code] - [code]major[/code] + [code]minor[/code] + [code]patch[/code] + [code]status[/code] + [code]build[/code] in a single String - The [code]hex[/code] value is encoded as follows, from left to right: one byte for the major, one byte for the minor, one byte for the patch version. For example, "3.1.12" would be [code]0x03010C[/code]. [b]Note:[/b] It's still an int internally, and printing it will give you its decimal representation, which is not particularly meaningful. Use hexadecimal literals for easy version comparisons from code: + Returns the current engine version information as a [Dictionary] containing the following entries: + - [code]major[/code] - Major version number as an int; + - [code]minor[/code] - Minor version number as an int; + - [code]patch[/code] - Patch version number as an int; + - [code]hex[/code] - Full version encoded as a hexadecimal int with one byte (2 hex digits) per number (see example below); + - [code]status[/code] - Status (such as "beta", "rc1", "rc2", "stable", etc.) as a String; + - [code]build[/code] - Build name (e.g. "custom_build") as a String; + - [code]hash[/code] - Full Git commit hash as a String; + - [code]timestamp[/code] - Holds the Git commit date UNIX timestamp in seconds as an int, or [code]0[/code] if unavailable; + - [code]string[/code] - [code]major[/code], [code]minor[/code], [code]patch[/code], [code]status[/code], and [code]build[/code] in a single String. + The [code]hex[/code] value is encoded as follows, from left to right: one byte for the major, one byte for the minor, one byte for the patch version. For example, "3.1.12" would be [code]0x03010C[/code]. + [b]Note:[/b] The [code]hex[/code] value is still an [int] internally, and printing it will give you its decimal representation, which is not particularly meaningful. Use hexadecimal literals for quick version comparisons from code: [codeblocks] [gdscript] - if Engine.get_version_info().hex >= 0x030200: - # Do things specific to version 3.2 or later + if Engine.get_version_info().hex >= 0x040100: + pass # Do things specific to version 4.1 or later. else: - # Do things specific to versions before 3.2 + pass # Do things specific to versions before 4.1. [/gdscript] [csharp] - if ((int)Engine.GetVersionInfo()["hex"] >= 0x030200) + if ((int)Engine.GetVersionInfo()["hex"] >= 0x040100) { - // Do things specific to version 3.2 or later + // Do things specific to version 4.1 or later. } else { - // Do things specific to versions before 3.2 + // Do things specific to versions before 4.1. } [/csharp] [/codeblocks] @@ -205,20 +207,35 @@ <method name="get_write_movie_path" qualifiers="const"> <return type="String" /> <description> - Returns the path to the [MovieWriter]'s output file, or an empty string if the engine wasn't started in Movie Maker mode. This path can be absolute or relative depending on how the user specified it. + Returns the path to the [MovieWriter]'s output file, or an empty string if the engine wasn't started in Movie Maker mode. The default path can be changed in [member ProjectSettings.editor/movie_writer/movie_file]. </description> </method> <method name="has_singleton" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if a singleton with given [param name] exists in global scope. + Returns [code]true[/code] if a singleton with the given [param name] exists in the global scope. See also [method get_singleton]. + [codeblocks] + [gdscript] + print(Engine.has_singleton("OS")) # Prints true + print(Engine.has_singleton("Engine")) # Prints true + print(Engine.has_singleton("AudioServer")) # Prints true + print(Engine.has_singleton("Unknown")) # Prints false + [/gdscript] + [csharp] + GD.Print(Engine.HasSingleton("OS")); // Prints true + GD.Print(Engine.HasSingleton("Engine")); // Prints true + GD.Print(Engine.HasSingleton("AudioServer")); // Prints true + GD.Print(Engine.HasSingleton("Unknown")); // Prints false + [/csharp] + [/codeblocks] + [b]Note:[/b] Global singletons are not the same as autoloaded nodes, which are configurable in the project settings. </description> </method> <method name="is_editor_hint" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the script is currently running inside the editor, [code]false[/code] otherwise. This is useful for [code]@tool[/code] scripts to conditionally draw editor helpers, or prevent accidentally running "game" code that would affect the scene state while in the editor: + Returns [code]true[/code] if the script is currently running inside the editor, otherwise returns [code]false[/code]. This is useful for [code]@tool[/code] scripts to conditionally draw editor helpers, or prevent accidentally running "game" code that would affect the scene state while in the editor: [codeblocks] [gdscript] if Engine.is_editor_hint(): @@ -234,13 +251,25 @@ [/csharp] [/codeblocks] See [url=$DOCS_URL/tutorials/plugins/running_code_in_the_editor.html]Running code in the editor[/url] in the documentation for more information. - [b]Note:[/b] To detect whether the script is run from an editor [i]build[/i] (e.g. when pressing [kbd]F5[/kbd]), use [method OS.has_feature] with the [code]"editor"[/code] argument instead. [code]OS.has_feature("editor")[/code] will evaluate to [code]true[/code] both when the code is running in the editor and when running the project from the editor, but it will evaluate to [code]false[/code] when the code is run from an exported project. + [b]Note:[/b] To detect whether the script is running on an editor [i]build[/i] (such as when pressing [kbd]F5[/kbd]), use [method OS.has_feature] with the [code]"editor"[/code] argument instead. [code]OS.has_feature("editor")[/code] evaluate to [code]true[/code] both when the script is running in the editor and when running the project from the editor, but returns [code]false[/code] when run from an exported project. </description> </method> <method name="is_in_physics_frame" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the game is inside the fixed process and physics phase of the game loop. + Returns [code]true[/code] if the engine is inside the fixed physics process step of the main loop. + [codeblock] + func _enter_tree(): + # Depending on when the node is added to the tree, + # prints either "true" or "false". + print(Engine.is_in_physics_frame()) + + func _process(delta): + print(Engine.is_in_physics_frame()) # Prints false + + func _physics_process(delta): + print(Engine.is_in_physics_frame()) # Prints true + [/codeblock] </description> </method> <method name="register_script_language"> @@ -249,9 +278,9 @@ <description> Registers a [ScriptLanguage] instance to be available with [code]ScriptServer[/code]. Returns: - - [constant OK] on success - - [constant ERR_UNAVAILABLE] if [code]ScriptServer[/code] has reached it limit and cannot register any new language - - [constant ERR_ALREADY_EXISTS] if [code]ScriptServer[/code] already contains a language with similar extension/name/type + - [constant OK] on success; + - [constant ERR_UNAVAILABLE] if [code]ScriptServer[/code] has reached the limit and cannot register any new language; + - [constant ERR_ALREADY_EXISTS] if [code]ScriptServer[/code] already contains a language with similar extension/name/type. </description> </method> <method name="register_singleton"> @@ -259,7 +288,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="instance" type="Object" /> <description> - Registers the given object as a singleton, globally available under [param name]. + Registers the given [Object] [param instance] as a singleton, available globally under [param name]. Useful for plugins. </description> </method> <method name="unregister_script_language"> @@ -268,33 +297,36 @@ <description> Unregisters the [ScriptLanguage] instance from [code]ScriptServer[/code]. Returns: - - [constant OK] on success - - [constant ERR_DOES_NOT_EXIST] if the language is already not registered in [code]ScriptServer[/code] + - [constant OK] on success; + - [constant ERR_DOES_NOT_EXIST] if the language is not registered in [code]ScriptServer[/code]. </description> </method> <method name="unregister_singleton"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Unregisters the singleton registered under [param name]. The singleton object is not freed. Only works with user-defined singletons created with [method register_singleton]. + Removes the singleton registered under [param name]. The singleton object is [i]not[/i] freed. Only works with user-defined singletons registered with [method register_singleton]. </description> </method> </methods> <members> <member name="max_fps" type="int" setter="set_max_fps" getter="get_max_fps" default="0"> - The maximum number of frames per second that can be rendered. A value of [code]0[/code] means "no limit". The actual number of frames per second may still be below this value if the CPU or GPU cannot keep up with the project logic and rendering. - Limiting the FPS can be useful to reduce system power consumption, which reduces heat and noise emissions (and improves battery life on mobile devices). - If [member ProjectSettings.display/window/vsync/vsync_mode] is [code]Enabled[/code] or [code]Adaptive[/code], it takes precedence and the forced FPS number cannot exceed the monitor's refresh rate. - If [member ProjectSettings.display/window/vsync/vsync_mode] is [code]Enabled[/code], on monitors with variable refresh rate enabled (G-Sync/FreeSync), using a FPS limit a few frames lower than the monitor's refresh rate will [url=https://blurbusters.com/howto-low-lag-vsync-on/]reduce input lag while avoiding tearing[/url]. - If [member ProjectSettings.display/window/vsync/vsync_mode] is [code]Disabled[/code], limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios. + The maximum number of frames that can be rendered every second (FPS). A value of [code]0[/code] means the framerate is uncapped. + Limiting the FPS can be useful to reduce the host machine's power consumption, which reduces heat, noise emissions, and improves battery life. + If [member ProjectSettings.display/window/vsync/vsync_mode] is [b]Enabled[/b] or [b]Adaptive[/b], the setting takes precedence and the max FPS number cannot exceed the monitor's refresh rate. + If [member ProjectSettings.display/window/vsync/vsync_mode] is [b]Enabled[/b], on monitors with variable refresh rate enabled (G-Sync/FreeSync), using an FPS limit a few frames lower than the monitor's refresh rate will [url=https://blurbusters.com/howto-low-lag-vsync-on/]reduce input lag while avoiding tearing[/url]. See also [member physics_ticks_per_second] and [member ProjectSettings.application/run/max_fps]. + [b]Note:[/b] The actual number of frames per second may still be below this value if the CPU or GPU cannot keep up with the project's logic and rendering. + [b]Note:[/b] If [member ProjectSettings.display/window/vsync/vsync_mode] is [b]Disabled[/b], limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios. </member> <member name="max_physics_steps_per_frame" type="int" setter="set_max_physics_steps_per_frame" getter="get_max_physics_steps_per_frame" default="8"> - Controls the maximum number of physics steps that can be simulated each rendered frame. The default value is tuned to avoid "spiral of death" situations where expensive physics simulations trigger more expensive simulations indefinitely. However, the game will appear to slow down if the rendering FPS is less than [code]1 / max_physics_steps_per_frame[/code] of [member physics_ticks_per_second]. This occurs even if [code]delta[/code] is consistently used in physics calculations. To avoid this, increase [member max_physics_steps_per_frame] if you have increased [member physics_ticks_per_second] significantly above its default value. + The maximum number of physics steps that can be simulated each rendered frame. + [b]Note:[/b] The default value is tuned to prevent expensive physics simulations from triggering even more expensive simulations indefinitely. However, the game will appear to slow down if the rendering FPS is less than [code]1 / max_physics_steps_per_frame[/code] of [member physics_ticks_per_second]. This occurs even if [code]delta[/code] is consistently used in physics calculations. To avoid this, increase [member max_physics_steps_per_frame] if you have increased [member physics_ticks_per_second] significantly above its default value. </member> <member name="physics_jitter_fix" type="float" setter="set_physics_jitter_fix" getter="get_physics_jitter_fix" default="0.5"> - Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of the in-game clock and real clock but smooth out framerate jitters. The default value of 0.5 should be fine for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. - [b]Note:[/b] For best results, when using a custom physics interpolation solution, the physics jitter fix should be disabled by setting [member physics_jitter_fix] to [code]0[/code]. + How much physics ticks are synchronized with real time. If [code]0[/code] or less, the ticks are fully synchronized. Higher values cause the in-game clock to deviate more from the real clock, but they smooth out framerate jitters. + [b]Note:[/b] The default value of [code]0.5[/code] should be good enough for most cases; values above [code]2[/code] could cause the game to react to dropped frames with a noticeable delay and are not recommended. + [b]Note:[/b] When using a custom physics interpolation solution, or within a network game, it's recommended to disable the physics jitter fix by setting this property to [code]0[/code]. </member> <member name="physics_ticks_per_second" type="int" setter="set_physics_ticks_per_second" getter="get_physics_ticks_per_second" default="60"> The number of fixed iterations per second. This controls how often physics simulation and [method Node._physics_process] methods are run. This value should generally always be set to [code]60[/code] or above, as Godot doesn't interpolate the physics step. As a result, values lower than [code]60[/code] will look stuttery. This value can be increased to make input more reactive or work around collision tunneling issues, but keep in mind doing so will increase CPU usage. See also [member max_fps] and [member ProjectSettings.physics/common/physics_ticks_per_second]. @@ -302,11 +334,15 @@ </member> <member name="print_error_messages" type="bool" setter="set_print_error_messages" getter="is_printing_error_messages" default="true"> If [code]false[/code], stops printing error and warning messages to the console and editor Output log. This can be used to hide error and warning messages during unit test suite runs. This property is equivalent to the [member ProjectSettings.application/run/disable_stderr] project setting. - [b]Warning:[/b] If you set this to [code]false[/code] anywhere in the project, important error messages may be hidden even if they are emitted from other scripts. If this is set to [code]false[/code] in a [code]@tool[/code] script, this will also impact the editor itself. Do [i]not[/i] report bugs before ensuring error messages are enabled (as they are by default). [b]Note:[/b] This property does not impact the editor's Errors tab when running a project from the editor. + [b]Warning:[/b] If set to [code]false[/code] anywhere in the project, important error messages may be hidden even if they are emitted from other scripts. In a [code]@tool[/code] script, this will also impact the editor itself. Do [i]not[/i] report bugs before ensuring error messages are enabled (as they are by default). </member> <member name="time_scale" type="float" setter="set_time_scale" getter="get_time_scale" default="1.0"> - Controls how fast or slow the in-game clock ticks versus the real life one. It defaults to 1.0. A value of 2.0 means the game moves twice as fast as real life, whilst a value of 0.5 means the game moves at half the regular speed. This also affects [Timer] and [SceneTreeTimer] (see [method SceneTree.create_timer] for how to control this). + The speed multiplier at which the in-game clock updates, compared to real time. For example, if set to [code]2.0[/code] the game runs twice as fast, and if set to [code]0.5[/code] the game runs half as fast. + This value affects [Timer], [SceneTreeTimer], and all other simulations that make use of [code]delta[/code] time (such as [method Node._process] and [method Node._physics_process]). + [b]Note:[/b] It's recommended to keep this property above [code]0.0[/code], as the game may behave unexpectedly otherwise. + [b]Note:[/b] This does not affect audio playback speed. Use [member AudioServer.playback_speed_scale] to adjust audio playback speed independently of [member Engine.time_scale]. + [b]Note:[/b] This does not automatically adjust [member physics_ticks_per_second]. With values above [code]1.0[/code] physics simulation may become less precise, as each physics tick will stretch over a larger period of engine time. If you're modifying [member Engine.time_scale] to speed up simulation by a large factor, consider also increasing [member physics_ticks_per_second] to make the simulation more reliable. </member> </members> </class> diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index acd959d7f7..189517c392 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -87,7 +87,18 @@ This is useful to simulate [url=https://en.wikipedia.org/wiki/Aerial_perspective]aerial perspective[/url] in large scenes with low density fog. However, it is not very useful for high-density fog, as the sky will shine through. When set to [code]1.0[/code], the fog color comes completely from the [Sky]. If set to [code]0.0[/code], aerial perspective is disabled. </member> <member name="fog_density" type="float" setter="set_fog_density" getter="get_fog_density" default="0.01"> - The [i]exponential[/i] fog density to use. Higher values result in a more dense fog. Fog rendering is exponential as in real life. + The fog density to be used. This is demonstrated in different ways depending on the [member fog_mode] mode chosen: + [b]Exponential Fog Mode:[/b] Higher values result in denser fog. The fog rendering is exponential like in real life. + [b]Depth Fog mode:[/b] The maximum intensity of the deep fog, effect will appear in the distance (relative to the camera). At [code]1.0[/code] the fog will fully obscure the scene, at [code]0.0[/code] the fog will not be visible. + </member> + <member name="fog_depth_begin" type="float" setter="set_fog_depth_begin" getter="get_fog_depth_begin" default="10.0"> + The fog's depth starting distance from the camera. Only available when [member fog_mode] is set to [constant FOG_MODE_DEPTH]. + </member> + <member name="fog_depth_curve" type="float" setter="set_fog_depth_curve" getter="get_fog_depth_curve" default="1.0"> + The fog depth's intensity curve. A number of presets are available in the Inspector by right-clicking the curve. Only available when [member fog_mode] is set to [constant FOG_MODE_DEPTH]. + </member> + <member name="fog_depth_end" type="float" setter="set_fog_depth_end" getter="get_fog_depth_end" default="100.0"> + The fog's depth end distance from the camera. If this value is set to [code]0[/code], it will be equal to the current camera's [member Camera3D.far] value. Only available when [member fog_mode] is set to [constant FOG_MODE_DEPTH]. </member> <member name="fog_enabled" type="bool" setter="set_fog_enabled" getter="is_fog_enabled" default="false"> If [code]true[/code], fog effects are enabled. @@ -104,6 +115,9 @@ <member name="fog_light_energy" type="float" setter="set_fog_light_energy" getter="get_fog_light_energy" default="1.0"> The fog's brightness. Higher values result in brighter fog. </member> + <member name="fog_mode" type="int" setter="set_fog_mode" getter="get_fog_mode" enum="Environment.FogMode" default="0"> + The fog mode. See [enum FogMode] for possible values. + </member> <member name="fog_sky_affect" type="float" setter="set_fog_sky_affect" getter="get_fog_sky_affect" default="1.0"> The factor to use when affecting the sky with non-volumetric fog. [code]1.0[/code] means that fog can fully obscure the sky. Lower values reduce the impact of fog on sky rendering, with [code]0.0[/code] not affecting sky rendering at all. [b]Note:[/b] [member fog_sky_affect] has no visual effect if [member fog_aerial_perspective] is [code]1.0[/code]. @@ -113,13 +127,15 @@ </member> <member name="glow_blend_mode" type="int" setter="set_glow_blend_mode" getter="get_glow_blend_mode" enum="Environment.GlowBlendMode" default="2"> The glow blending mode. + [b]Note:[/b] [member glow_blend_mode] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_bloom" type="float" setter="set_glow_bloom" getter="get_glow_bloom" default="0.0"> The bloom's intensity. If set to a value higher than [code]0[/code], this will make glow visible in areas darker than the [member glow_hdr_threshold]. </member> <member name="glow_enabled" type="bool" setter="set_glow_enabled" getter="is_glow_enabled" default="false"> - If [code]true[/code], the glow effect is enabled. - [b]Note:[/b] Glow is only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, glow will look different due to the lower dynamic range available in the Mobile rendering method. + If [code]true[/code], the glow effect is enabled. This simulates real world eye/camera behavior where bright pixels bleed onto surrounding pixels. + [b]Note:[/b] When using the Mobile rendering method, glow looks different due to the lower dynamic range available in the Mobile rendering method. + [b]Note:[/b] When using the Compatibility rendering method, glow uses a different implementation with some properties being unavailable and hidden from the inspector: [code]glow_levels/*[/code], [member glow_normalized], [member glow_strength], [member glow_blend_mode], [member glow_mix], [member glow_map], and [member glow_map_strength]. This implementation is optimized to run on low-end devices and is less flexible as a result. </member> <member name="glow_hdr_luminance_cap" type="float" setter="set_glow_hdr_luminance_cap" getter="get_glow_hdr_luminance_cap" default="12.0"> The higher threshold of the HDR glow. Areas brighter than this threshold will be clamped for the purposes of the glow effect. @@ -135,40 +151,52 @@ </member> <member name="glow_levels/1" type="float" setter="set_glow_level" getter="get_glow_level" default="0.0"> The intensity of the 1st level of glow. This is the most "local" level (least blurry). + [b]Note:[/b] [member glow_levels/1] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_levels/2" type="float" setter="set_glow_level" getter="get_glow_level" default="0.0"> The intensity of the 2nd level of glow. + [b]Note:[/b] [member glow_levels/2] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_levels/3" type="float" setter="set_glow_level" getter="get_glow_level" default="1.0"> The intensity of the 3rd level of glow. + [b]Note:[/b] [member glow_levels/3] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_levels/4" type="float" setter="set_glow_level" getter="get_glow_level" default="0.0"> The intensity of the 4th level of glow. + [b]Note:[/b] [member glow_levels/4] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_levels/5" type="float" setter="set_glow_level" getter="get_glow_level" default="1.0"> The intensity of the 5th level of glow. + [b]Note:[/b] [member glow_levels/5] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_levels/6" type="float" setter="set_glow_level" getter="get_glow_level" default="0.0"> The intensity of the 6th level of glow. + [b]Note:[/b] [member glow_levels/6] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_levels/7" type="float" setter="set_glow_level" getter="get_glow_level" default="0.0"> The intensity of the 7th level of glow. This is the most "global" level (blurriest). + [b]Note:[/b] [member glow_levels/7] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_map" type="Texture" setter="set_glow_map" getter="get_glow_map"> The texture that should be used as a glow map to [i]multiply[/i] the resulting glow color according to [member glow_map_strength]. This can be used to create a "lens dirt" effect. The texture's RGB color channels are used for modulation, but the alpha channel is ignored. [b]Note:[/b] The texture will be stretched to fit the screen. Therefore, it's recommended to use a texture with an aspect ratio that matches your project's base aspect ratio (typically 16:9). + [b]Note:[/b] [member glow_map] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_map_strength" type="float" setter="set_glow_map_strength" getter="get_glow_map_strength" default="0.8"> How strong of an impact the [member glow_map] should have on the overall glow effect. A strength of [code]0.0[/code] means the glow map has no effect on the overall glow effect. A strength of [code]1.0[/code] means the glow has a full effect on the overall glow effect (and can turn off glow entirely in specific areas of the screen if the glow map has black areas). + [b]Note:[/b] [member glow_map_strength] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_mix" type="float" setter="set_glow_mix" getter="get_glow_mix" default="0.05"> When using the [constant GLOW_BLEND_MODE_MIX] [member glow_blend_mode], this controls how much the source image is blended with the glow layer. A value of [code]0.0[/code] makes the glow rendering invisible, while a value of [code]1.0[/code] is equivalent to [constant GLOW_BLEND_MODE_REPLACE]. + [b]Note:[/b] [member glow_mix] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_normalized" type="bool" setter="set_glow_normalized" getter="is_glow_normalized" default="false"> If [code]true[/code], glow levels will be normalized so that summed together their intensities equal [code]1.0[/code]. + [b]Note:[/b] [member glow_normalized] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_strength" type="float" setter="set_glow_strength" getter="get_glow_strength" default="1.0"> The strength of the glow effect. This applies as the glow is blurred across the screen and increases the distance and intensity of the blur. When using the Mobile rendering method, this should be increased to compensate for the lower dynamic range. + [b]Note:[/b] [member glow_strength] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="reflected_light_source" type="int" setter="set_reflection_source" getter="get_reflection_source" enum="Environment.ReflectionSource" default="0"> The reflected (specular) light source. @@ -289,7 +317,7 @@ The default exposure used for tonemapping. Higher values result in a brighter image. See also [member tonemap_white]. </member> <member name="tonemap_mode" type="int" setter="set_tonemapper" getter="get_tonemapper" enum="Environment.ToneMapper" default="0"> - The tonemapping mode to use. Tonemapping is the process that "converts" HDR values to be suitable for rendering on a LDR display. (Godot doesn't support rendering on HDR displays yet.) + The tonemapping mode to use. Tonemapping is the process that "converts" HDR values to be suitable for rendering on an LDR display. (Godot doesn't support rendering on HDR displays yet.) </member> <member name="tonemap_white" type="float" setter="set_tonemap_white" getter="get_tonemap_white" default="1.0"> The white reference value for tonemapping (also called "whitepoint"). Higher values can make highlights look less blown out, and will also slightly darken the whole scene as a result. Only effective if the [member tonemap_mode] isn't set to [constant TONE_MAPPER_LINEAR]. See also [member tonemap_exposure]. @@ -412,6 +440,12 @@ <constant name="GLOW_BLEND_MODE_MIX" value="4" enum="GlowBlendMode"> Mixes the glow with the underlying color to avoid increasing brightness as much while still maintaining a glow effect. </constant> + <constant name="FOG_MODE_EXPONENTIAL" value="0" enum="FogMode"> + Use a physically-based fog model defined primarily by fog density. + </constant> + <constant name="FOG_MODE_DEPTH" value="1" enum="FogMode"> + Use a simple fog model defined by start and end positions and a custom curve. While not physically accurate, this model can be useful when you need more artistic control. + </constant> <constant name="SDFGI_Y_SCALE_50_PERCENT" value="0" enum="SDFGIYScale"> Use 50% scale for SDFGI on the Y (vertical) axis. SDFGI cells will be twice as short as they are wide. This allows providing increased GI detail and reduced light leaking with thin floors and ceilings. This is usually the best choice for scenes that don't feature much verticality. </constant> diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml index d1b20a3890..fad6cbcc93 100644 --- a/doc/classes/FileAccess.xml +++ b/doc/classes/FileAccess.xml @@ -39,6 +39,7 @@ </description> <tutorials> <link title="File system">$DOCS_URL/tutorials/scripting/filesystem.html</link> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> <link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/676</link> </tutorials> <methods> @@ -256,7 +257,7 @@ <return type="String" /> <param index="0" name="path" type="String" /> <description> - Returns a SHA-256 [String] representing the file at the given path or an empty [String] on failure. + Returns an SHA-256 [String] representing the file at the given path or an empty [String] on failure. </description> </method> <method name="get_unix_permissions" qualifiers="static"> @@ -516,12 +517,14 @@ </constant> <constant name="WRITE" value="2" enum="ModeFlags"> Opens the file for write operations. The file is created if it does not exist, and truncated if it does. + [b]Note:[/b] When creating a file it must be in an already existing directory. To recursively create directories for a file path, see [method DirAccess.make_dir_recursive]). </constant> <constant name="READ_WRITE" value="3" enum="ModeFlags"> Opens the file for read and write operations. Does not truncate the file. The cursor is positioned at the beginning of the file. </constant> <constant name="WRITE_READ" value="7" enum="ModeFlags"> Opens the file for read and write operations. The file is created if it does not exist, and truncated if it does. The cursor is positioned at the beginning of the file. + [b]Note:[/b] When creating a file it must be in an already existing directory. To recursively create directories for a file path, see [method DirAccess.make_dir_recursive]). </constant> <constant name="COMPRESSION_FASTLZ" value="0" enum="CompressionMode"> Uses the [url=https://fastlz.org/]FastLZ[/url] compression method. diff --git a/doc/classes/FileDialog.xml b/doc/classes/FileDialog.xml index 75856e91d8..dec3160ffe 100644 --- a/doc/classes/FileDialog.xml +++ b/doc/classes/FileDialog.xml @@ -19,6 +19,16 @@ For example, a [param filter] of [code]"*.png, *.jpg"[/code] and a [param description] of [code]"Images"[/code] results in filter text "Images (*.png, *.jpg)". </description> </method> + <method name="add_option"> + <return type="void" /> + <param index="0" name="name" type="String" /> + <param index="1" name="values" type="PackedStringArray" /> + <param index="2" name="default_value_index" type="int" /> + <description> + Adds an additional [OptionButton] to the file dialog. If [param values] is empty, a [CheckBox] is added instead. + [param default_value_index] should be an index of the value in the [param values]. If [param values] is empty it should be either [code]1[/code] (checked), or [code]0[/code] (unchecked). + </description> + </method> <method name="clear_filters"> <return type="void" /> <description> @@ -38,6 +48,33 @@ [b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member CanvasItem.visible] property. </description> </method> + <method name="get_option_default" qualifiers="const"> + <return type="int" /> + <param index="0" name="option" type="int" /> + <description> + Returns the default value index of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="get_option_name" qualifiers="const"> + <return type="String" /> + <param index="0" name="option" type="int" /> + <description> + Returns the name of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="get_option_values" qualifiers="const"> + <return type="PackedStringArray" /> + <param index="0" name="option" type="int" /> + <description> + Returns an array of values of the [OptionButton] with index [param option]. + </description> + </method> + <method name="get_selected_options" qualifiers="const"> + <return type="Dictionary" /> + <description> + Returns a [Dictionary] with the selected values of the additional [OptionButton]s and/or [CheckBox]es. [Dictionary] keys are names and values are selected value indices. + </description> + </method> <method name="get_vbox"> <return type="VBoxContainer" /> <description> @@ -51,6 +88,30 @@ Invalidate and update the current dialog content list. </description> </method> + <method name="set_option_default"> + <return type="void" /> + <param index="0" name="option" type="int" /> + <param index="1" name="default_value_index" type="int" /> + <description> + Sets the default value index of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="set_option_name"> + <return type="void" /> + <param index="0" name="option" type="int" /> + <param index="1" name="name" type="String" /> + <description> + Sets the name of the [OptionButton] or [CheckBox] with index [param option]. + </description> + </method> + <method name="set_option_values"> + <return type="void" /> + <param index="0" name="option" type="int" /> + <param index="1" name="values" type="PackedStringArray" /> + <description> + Sets the option values of the [OptionButton] with index [param option]. + </description> + </method> </methods> <members> <member name="access" type="int" setter="set_access" getter="get_access" enum="FileDialog.Access" default="0"> @@ -71,11 +132,14 @@ The dialog's open or save mode, which affects the selection behavior. See [enum FileMode]. </member> <member name="filters" type="PackedStringArray" setter="set_filters" getter="get_filters" default="PackedStringArray()"> - The available file type filters. For example, this shows only [code].png[/code] and [code].gd[/code] files: [code]set_filters(PackedStringArray(["*.png ; PNG Images","*.gd ; GDScript Files"]))[/code]. Multiple file types can also be specified in a single filter. [code]"*.png, *.jpg, *.jpeg ; Supported Images"[/code] will show both PNG and JPEG files when selected. + The available file type filters. Each filter string in the array should be formatted like this: [code]*.txt,*.doc;Text Files[/code]. The description text of the filter is optional and can be omitted. </member> <member name="mode_overrides_title" type="bool" setter="set_mode_overrides_title" getter="is_mode_overriding_title" default="true"> If [code]true[/code], changing the [member file_mode] property will set the window title accordingly (e.g. setting [member file_mode] to [constant FILE_MODE_OPEN_FILE] will change the window title to "Open a File"). </member> + <member name="option_count" type="int" setter="set_option_count" getter="get_option_count" default="0"> + The number of additional [OptionButton]s and [CheckBox]es in the dialog. + </member> <member name="root_subfolder" type="String" setter="set_root_subfolder" getter="get_root_subfolder" default=""""> If non-empty, the given sub-folder will be "root" of this [FileDialog], i.e. user won't be able to go to its parent directory. </member> @@ -147,6 +211,9 @@ <theme_item name="back_folder" data_type="icon" type="Texture2D"> Custom icon for the back arrow. </theme_item> + <theme_item name="create_folder" data_type="icon" type="Texture2D"> + Custom icon for the create folder button. + </theme_item> <theme_item name="file" data_type="icon" type="Texture2D"> Custom icon for files. </theme_item> diff --git a/doc/classes/FlowContainer.xml b/doc/classes/FlowContainer.xml index 14e84b40e6..5e767acf7d 100644 --- a/doc/classes/FlowContainer.xml +++ b/doc/classes/FlowContainer.xml @@ -21,6 +21,10 @@ <member name="alignment" type="int" setter="set_alignment" getter="get_alignment" enum="FlowContainer.AlignmentMode" default="0"> The alignment of the container's children (must be one of [constant ALIGNMENT_BEGIN], [constant ALIGNMENT_CENTER], or [constant ALIGNMENT_END]). </member> + <member name="reverse_fill" type="bool" setter="set_reverse_fill" getter="is_reverse_fill" default="false"> + If [code]true[/code], reverses fill direction. Horizontal [FlowContainer]s will fill rows bottom to top, vertical [FlowContainer]s will fill columns right to left. + When using a vertical [FlowContainer] with a right to left [member Control.layout_direction], columns will fill left to right instead. + </member> <member name="vertical" type="bool" setter="set_vertical" getter="is_vertical" default="false"> If [code]true[/code], the [FlowContainer] will arrange its children vertically, rather than horizontally. Can't be changed when using [HFlowContainer] and [VFlowContainer]. @@ -39,10 +43,10 @@ </constants> <theme_items> <theme_item name="h_separation" data_type="constant" type="int" default="4"> - The horizontal separation of children nodes. + The horizontal separation of child nodes. </theme_item> <theme_item name="v_separation" data_type="constant" type="int" default="4"> - The vertical separation of children nodes. + The vertical separation of child nodes. </theme_item> </theme_items> </class> diff --git a/doc/classes/FogMaterial.xml b/doc/classes/FogMaterial.xml index a6acaaef00..f256555d86 100644 --- a/doc/classes/FogMaterial.xml +++ b/doc/classes/FogMaterial.xml @@ -10,7 +10,7 @@ <tutorials> </tutorials> <members> - <member name="albedo" type="Color" setter="set_albedo" getter="get_albedo" default="Color(1, 1, 1, 1)"> + <member name="albedo" type="Color" setter="set_albedo" getter="get_albedo" default="Color(1, 1, 1, 1)" keywords="color, colour"> The single-scattering [Color] of the [FogVolume]. Internally, [member albedo] is converted into single-scattering, which is additively blended with other [FogVolume]s and the [member Environment.volumetric_fog_albedo]. </member> <member name="density" type="float" setter="set_density" getter="get_density" default="1.0"> diff --git a/doc/classes/Font.xml b/doc/classes/Font.xml index 63e7d80737..e979a0b875 100644 --- a/doc/classes/Font.xml +++ b/doc/classes/Font.xml @@ -118,6 +118,7 @@ <param index="5" name="spacing_bottom" type="int" default="0" /> <param index="6" name="spacing_space" type="int" default="0" /> <param index="7" name="spacing_glyph" type="int" default="0" /> + <param index="8" name="baseline_offset" type="float" default="0.0" /> <description> Returns [TextServer] RID of the font cache for specific variation. </description> @@ -135,7 +136,7 @@ <param index="0" name="char" type="int" /> <param index="1" name="font_size" type="int" /> <description> - Returns the size of a character, optionally taking kerning into account if the next character is provided. + Returns the size of a character. Does not take kerning into account. [b]Note:[/b] Do not use this function to calculate width of the string character by character, use [method get_string_size] or [TextLine] instead. The height returned is the font height (see also [method get_height]) and has no relation to the glyph height. </description> </method> diff --git a/doc/classes/FontFile.xml b/doc/classes/FontFile.xml index 53d367817d..1b8fa00772 100644 --- a/doc/classes/FontFile.xml +++ b/doc/classes/FontFile.xml @@ -28,6 +28,7 @@ [/codeblocks] </description> <tutorials> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="clear_cache"> @@ -41,7 +42,7 @@ <param index="0" name="cache_index" type="int" /> <param index="1" name="size" type="Vector2i" /> <description> - Removes all rendered glyphs information from the cache entry. + Removes all rendered glyph information from the cache entry. [b]Note:[/b] This function will not remove textures associated with the glyphs, use [method remove_texture] to remove them manually. </description> </method> @@ -130,6 +131,13 @@ Returns embolden strength, if is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness. </description> </method> + <method name="get_extra_baseline_offset" qualifiers="const"> + <return type="float" /> + <param index="0" name="cache_index" type="int" /> + <description> + Returns extra baseline offset (as a fraction of font height). + </description> + </method> <method name="get_extra_spacing" qualifiers="const"> <return type="int" /> <param index="0" name="cache_index" type="int" /> @@ -444,6 +452,14 @@ Sets embolden strength, if is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness. </description> </method> + <method name="set_extra_baseline_offset"> + <return type="void" /> + <param index="0" name="cache_index" type="int" /> + <param index="1" name="baseline_offset" type="float" /> + <description> + Sets extra baseline offset (as a fraction of font height). + </description> + </method> <method name="set_extra_spacing"> <return type="void" /> <param index="0" name="cache_index" type="int" /> @@ -563,7 +579,7 @@ <param index="0" name="cache_index" type="int" /> <param index="1" name="transform" type="Transform2D" /> <description> - Sets 2D transform, applied to the font outlines, can be used for slanting, flipping and rotating glyphs. + Sets 2D transform, applied to the font outlines, can be used for slanting, flipping, and rotating glyphs. </description> </method> <method name="set_variation_coordinates"> @@ -585,6 +601,9 @@ <member name="data" type="PackedByteArray" setter="set_data" getter="get_data" default="PackedByteArray()"> Contents of the dynamic font source file. </member> + <member name="disable_embedded_bitmaps" type="bool" setter="set_disable_embedded_bitmaps" getter="get_disable_embedded_bitmaps" default="true"> + If set to [code]true[/code], embedded font bitmap loading is disabled (bitmap-only and color fonts ignore this property). + </member> <member name="fixed_size" type="int" setter="set_fixed_size" getter="get_fixed_size" default="0"> Font size, used only for the bitmap fonts. </member> diff --git a/doc/classes/FontVariation.xml b/doc/classes/FontVariation.xml index e21881fc3e..8a09c49f48 100644 --- a/doc/classes/FontVariation.xml +++ b/doc/classes/FontVariation.xml @@ -46,6 +46,9 @@ <member name="base_font" type="Font" setter="set_base_font" getter="get_base_font"> Base font used to create a variation. If not set, default [Theme] font is used. </member> + <member name="baseline_offset" type="float" setter="set_baseline_offset" getter="get_baseline_offset" default="0.0"> + Extra baseline offset (as a fraction of font height). + </member> <member name="opentype_features" type="Dictionary" setter="set_opentype_features" getter="get_opentype_features" default="{}"> A set of OpenType feature tags. More info: [url=https://docs.microsoft.com/en-us/typography/opentype/spec/featuretags]OpenType feature tags[/url]. </member> diff --git a/doc/classes/FramebufferCacheRD.xml b/doc/classes/FramebufferCacheRD.xml new file mode 100644 index 0000000000..f4424311bf --- /dev/null +++ b/doc/classes/FramebufferCacheRD.xml @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="FramebufferCacheRD" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Framebuffer cache manager for Rendering Device based renderers. + </brief_description> + <description> + Framebuffer cache manager for Rendering Device based renderers. Provides a way to create a framebuffer and reuse it in subsequent calls for as long as the used textures exists. Framebuffers will automatically be cleaned up when dependent objects are freed. + </description> + <tutorials> + </tutorials> + <methods> + <method name="get_cache_multipass" qualifiers="static"> + <return type="RID" /> + <param index="0" name="textures" type="RID[]" /> + <param index="1" name="passes" type="RDFramebufferPass[]" /> + <param index="2" name="views" type="int" /> + <description> + Creates, or obtains a cached, framebuffer. [param textures] lists textures accessed. [param passes] defines the subpasses and texture allocation, if left empty a single pass is created and textures are allocated depending on their usage flags. [param views] defines the number of views used when rendering. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/GDExtension.xml b/doc/classes/GDExtension.xml index ee55c89131..c2d46dcf9e 100644 --- a/doc/classes/GDExtension.xml +++ b/doc/classes/GDExtension.xml @@ -1,49 +1,42 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="GDExtension" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + A native library for GDExtension. </brief_description> <description> + The [GDExtension] resource type represents a [url=https://en.wikipedia.org/wiki/Shared_library]shared library[/url] which can expand the functionality of the engine. The [GDExtensionManager] singleton is responsible for loading, reloading, and unloading [GDExtension] resources. + [b]Note:[/b] GDExtension itself is not a scripting language and has no relation to [GDScript] resources. </description> <tutorials> + <link title="GDExtension overview">$DOCS_URL/tutorials/scripting/gdextension/what_is_gdextension.html</link> + <link title="GDExtension example in C++">$DOCS_URL/tutorials/scripting/gdextension/gdextension_cpp_example.html</link> </tutorials> <methods> - <method name="close_library"> - <return type="void" /> - <description> - </description> - </method> <method name="get_minimum_library_initialization_level" qualifiers="const"> <return type="int" enum="GDExtension.InitializationLevel" /> <description> - </description> - </method> - <method name="initialize_library"> - <return type="void" /> - <param index="0" name="level" type="int" enum="GDExtension.InitializationLevel" /> - <description> + Returns the lowest level required for this extension to be properly initialized (see the [enum InitializationLevel] enum). </description> </method> <method name="is_library_open" qualifiers="const"> <return type="bool" /> <description> - </description> - </method> - <method name="open_library"> - <return type="int" enum="Error" /> - <param index="0" name="path" type="String" /> - <param index="1" name="entry_symbol" type="String" /> - <description> + Returns [code]true[/code] if this extension's library has been opened. </description> </method> </methods> <constants> <constant name="INITIALIZATION_LEVEL_CORE" value="0" enum="InitializationLevel"> + The library is initialized at the same time as the core features of the engine. </constant> <constant name="INITIALIZATION_LEVEL_SERVERS" value="1" enum="InitializationLevel"> + The library is initialized at the same time as the engine's servers (such as [RenderingServer] or [PhysicsServer3D]). </constant> <constant name="INITIALIZATION_LEVEL_SCENE" value="2" enum="InitializationLevel"> + The library is initialized at the same time as the engine's scene-related classes. </constant> <constant name="INITIALIZATION_LEVEL_EDITOR" value="3" enum="InitializationLevel"> + The library is initialized at the same time as the engine's editor classes. Only happens when loading the GDExtension in the editor. </constant> </constants> </class> diff --git a/doc/classes/GDExtensionManager.xml b/doc/classes/GDExtensionManager.xml index 8d2515dc28..1ecb23a03b 100644 --- a/doc/classes/GDExtensionManager.xml +++ b/doc/classes/GDExtensionManager.xml @@ -1,65 +1,82 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="GDExtensionManager" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Provides access to GDExtension functionality. </brief_description> <description> + The GDExtensionManager loads, initializes, and keeps track of all available [GDExtension] libraries in the project. + [b]Note:[/b] Do not worry about GDExtension unless you know what you are doing. </description> <tutorials> + <link title="GDExtension overview">$DOCS_URL/tutorials/scripting/gdextension/what_is_gdextension.html</link> + <link title="GDExtension example in C++">$DOCS_URL/tutorials/scripting/gdextension/gdextension_cpp_example.html</link> </tutorials> <methods> <method name="get_extension"> <return type="GDExtension" /> <param index="0" name="path" type="String" /> <description> + Returns the [GDExtension] at the given file [param path], or [code]null[/code] if it has not been loaded or does not exist. </description> </method> <method name="get_loaded_extensions" qualifiers="const"> <return type="PackedStringArray" /> <description> + Returns the file paths of all currently loaded extensions. </description> </method> <method name="is_extension_loaded" qualifiers="const"> <return type="bool" /> <param index="0" name="path" type="String" /> <description> + Returns [code]true[/code] if the extension at the given file [param path] has already been loaded successfully. See also [method get_loaded_extensions]. </description> </method> <method name="load_extension"> <return type="int" enum="GDExtensionManager.LoadStatus" /> <param index="0" name="path" type="String" /> <description> + Loads an extension by absolute file path. The [param path] needs to point to a valid [GDExtension]. Returns [constant LOAD_STATUS_OK] if successful. </description> </method> <method name="reload_extension"> <return type="int" enum="GDExtensionManager.LoadStatus" /> <param index="0" name="path" type="String" /> <description> + Reloads the extension at the given file path. The [param path] needs to point to a valid [GDExtension], otherwise this method may return either [constant LOAD_STATUS_NOT_LOADED] or [constant LOAD_STATUS_FAILED]. + [b]Note:[/b] You can only reload extensions in the editor. In release builds, this method always fails and returns [constant LOAD_STATUS_FAILED]. </description> </method> <method name="unload_extension"> <return type="int" enum="GDExtensionManager.LoadStatus" /> <param index="0" name="path" type="String" /> <description> + Unloads an extension by file path. The [param path] needs to point to an already loaded [GDExtension], otherwise this method returns [constant LOAD_STATUS_NOT_LOADED]. </description> </method> </methods> <signals> <signal name="extensions_reloaded"> <description> - Emitted after the editor has automatically reloaded any extensions. + Emitted after the editor has finished reloading one or more extensions. </description> </signal> </signals> <constants> <constant name="LOAD_STATUS_OK" value="0" enum="LoadStatus"> + The extension has loaded successfully. </constant> <constant name="LOAD_STATUS_FAILED" value="1" enum="LoadStatus"> + The extension has failed to load, possibly because it does not exist or has missing dependencies. </constant> <constant name="LOAD_STATUS_ALREADY_LOADED" value="2" enum="LoadStatus"> + The extension has already been loaded. </constant> <constant name="LOAD_STATUS_NOT_LOADED" value="3" enum="LoadStatus"> + The extension has not been loaded. </constant> <constant name="LOAD_STATUS_NEEDS_RESTART" value="4" enum="LoadStatus"> + The extension requires the application to restart to fully load. </constant> </constants> </class> diff --git a/doc/classes/GPUParticles2D.xml b/doc/classes/GPUParticles2D.xml index 2308ec43c5..f4ba305f8b 100644 --- a/doc/classes/GPUParticles2D.xml +++ b/doc/classes/GPUParticles2D.xml @@ -37,6 +37,7 @@ <param index="4" name="flags" type="int" /> <description> Emits a single particle. Whether [param xform], [param velocity], [param color] and [param custom] are applied depends on the value of [param flags]. See [enum EmitFlags]. + The default ParticleProcessMaterial will overwrite [param color] and use the contents of [param custom] as [code](rotation, age, animation, lifetime)[/code]. </description> </method> <method name="restart"> diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml index b5af63a8f4..d1903b85cd 100644 --- a/doc/classes/GPUParticles3D.xml +++ b/doc/classes/GPUParticles3D.xml @@ -35,6 +35,7 @@ <param index="4" name="flags" type="int" /> <description> Emits a single particle. Whether [param xform], [param velocity], [param color] and [param custom] are applied depends on the value of [param flags]. See [enum EmitFlags]. + The default ParticleProcessMaterial will overwrite [param color] and use the contents of [param custom] as [code](rotation, age, animation, lifetime)[/code]. </description> </method> <method name="get_draw_pass_mesh" qualifiers="const"> diff --git a/doc/classes/Geometry3D.xml b/doc/classes/Geometry3D.xml index a85d17d925..9f87682983 100644 --- a/doc/classes/Geometry3D.xml +++ b/doc/classes/Geometry3D.xml @@ -142,5 +142,12 @@ Tests if the segment ([param from], [param to]) intersects the triangle [param a], [param b], [param c]. If yes, returns the point of intersection as [Vector3]. If no intersection takes place, returns [code]null[/code]. </description> </method> + <method name="tetrahedralize_delaunay"> + <return type="PackedInt32Array" /> + <param index="0" name="points" type="PackedVector3Array" /> + <description> + Tetrahedralizes the volume specified by a discrete set of [param points] in 3D space, ensuring that no point lies within the circumsphere of any resulting tetrahedron. The method returns a [PackedInt32Array] where each tetrahedron consists of four consecutive point indices into the [param points] array (resulting in an array with [code]n * 4[/code] elements, where [code]n[/code] is the number of tetrahedra found). If the tetrahedralization is unsuccessful, an empty [PackedInt32Array] is returned. + </description> + </method> </methods> </class> diff --git a/doc/classes/GeometryInstance3D.xml b/doc/classes/GeometryInstance3D.xml index 990efbb3a4..e52a3d7683 100644 --- a/doc/classes/GeometryInstance3D.xml +++ b/doc/classes/GeometryInstance3D.xml @@ -34,7 +34,7 @@ The selected shadow casting flag. See [enum ShadowCastingSetting] for possible values. </member> <member name="custom_aabb" type="AABB" setter="set_custom_aabb" getter="get_custom_aabb" default="AABB(0, 0, 0, 0, 0, 0)"> - Overrides the bounding box of this node with a custom one. This can be used to avoid the expensive [AABB] recalculation that happens when a skeleton is used with a [MeshInstance3D] or to have fine control over the [MeshInstance3D]'s bounding box. To use the default AABB, set value to an [AABB] with all fields set to [code]0.0[/code]. To avoid frustum culling, set [member custom_aabb] to a very large AABB that covers your entire game world such as [code]AABB(-10000, -10000, -10000, 20000, 20000, 20000)[/code]. To disable all forms of culling (including occlusion culling), call [method RenderingServer.instance_set_ignore_culling] on the [GeometryInstance3D]'s [RID]. + Overrides the bounding box of this node with a custom one. This can be used to avoid the expensive [AABB] recalculation that happens when a skeleton is used with a [MeshInstance3D] or to have precise control over the [MeshInstance3D]'s bounding box. To use the default AABB, set value to an [AABB] with all fields set to [code]0.0[/code]. To avoid frustum culling, set [member custom_aabb] to a very large AABB that covers your entire game world such as [code]AABB(-10000, -10000, -10000, 20000, 20000, 20000)[/code]. To disable all forms of culling (including occlusion culling), call [method RenderingServer.instance_set_ignore_culling] on the [GeometryInstance3D]'s [RID]. </member> <member name="extra_cull_margin" type="float" setter="set_extra_cull_margin" getter="get_extra_cull_margin" default="0.0"> The extra distance added to the GeometryInstance3D's bounding box ([AABB]) to increase its cull box. @@ -42,7 +42,7 @@ <member name="gi_lightmap_scale" type="int" setter="set_lightmap_scale" getter="get_lightmap_scale" enum="GeometryInstance3D.LightmapScale" default="0"> The texel density to use for lightmapping in [LightmapGI]. Greater scale values provide higher resolution in the lightmap, which can result in sharper shadows for lights that have both direct and indirect light baked. However, greater scale values will also increase the space taken by the mesh in the lightmap texture, which increases the memory, storage, and bake time requirements. When using a single mesh at different scales, consider adjusting this value to keep the lightmap texel density consistent across meshes. </member> - <member name="gi_mode" type="int" setter="set_gi_mode" getter="get_gi_mode" enum="GeometryInstance3D.GIMode" default="1"> + <member name="gi_mode" type="int" setter="set_gi_mode" getter="get_gi_mode" enum="GeometryInstance3D.GIMode" default="1" keywords="global_illumination_mode, light_bake_mode"> The global illumination mode to use for the whole geometry. To avoid inconsistent results, use a mode that matches the purpose of the mesh during gameplay (static/dynamic). [b]Note:[/b] Lights' bake mode will also affect the global illumination rendering. See [member Light3D.light_bake_mode]. </member> @@ -62,26 +62,26 @@ The material override for the whole geometry. If a material is assigned to this property, it will be used instead of any material set in any material slot of the mesh. </member> - <member name="transparency" type="float" setter="set_transparency" getter="get_transparency" default="0.0"> + <member name="transparency" type="float" setter="set_transparency" getter="get_transparency" default="0.0" keywords="opacity"> The transparency applied to the whole geometry (as a multiplier of the materials' existing transparency). [code]0.0[/code] is fully opaque, while [code]1.0[/code] is fully transparent. Values greater than [code]0.0[/code] (exclusive) will force the geometry's materials to go through the transparent pipeline, which is slower to render and can exhibit rendering issues due to incorrect transparency sorting. However, unlike using a transparent material, setting [member transparency] to a value greater than [code]0.0[/code] (exclusive) will [i]not[/i] disable shadow rendering. In spatial shaders, [code]1.0 - transparency[/code] is set as the default value of the [code]ALPHA[/code] built-in. [b]Note:[/b] [member transparency] is clamped between [code]0.0[/code] and [code]1.0[/code], so this property cannot be used to make transparent materials more opaque than they originally are. </member> - <member name="visibility_range_begin" type="float" setter="set_visibility_range_begin" getter="get_visibility_range_begin" default="0.0"> + <member name="visibility_range_begin" type="float" setter="set_visibility_range_begin" getter="get_visibility_range_begin" default="0.0" keywords="lod_begin, hlod_begin"> Starting distance from which the GeometryInstance3D will be visible, taking [member visibility_range_begin_margin] into account as well. The default value of 0 is used to disable the range check. </member> - <member name="visibility_range_begin_margin" type="float" setter="set_visibility_range_begin_margin" getter="get_visibility_range_begin_margin" default="0.0"> + <member name="visibility_range_begin_margin" type="float" setter="set_visibility_range_begin_margin" getter="get_visibility_range_begin_margin" default="0.0" keywords="lod_begin_margin, hlod_begin_margin"> Margin for the [member visibility_range_begin] threshold. The GeometryInstance3D will only change its visibility state when it goes over or under the [member visibility_range_begin] threshold by this amount. If [member visibility_range_fade_mode] is [constant VISIBILITY_RANGE_FADE_DISABLED], this acts as a hysteresis distance. If [member visibility_range_fade_mode] is [constant VISIBILITY_RANGE_FADE_SELF] or [constant VISIBILITY_RANGE_FADE_DEPENDENCIES], this acts as a fade transition distance and must be set to a value greater than [code]0.0[/code] for the effect to be noticeable. </member> - <member name="visibility_range_end" type="float" setter="set_visibility_range_end" getter="get_visibility_range_end" default="0.0"> + <member name="visibility_range_end" type="float" setter="set_visibility_range_end" getter="get_visibility_range_end" default="0.0" keywords="lod_end, hlod_end"> Distance from which the GeometryInstance3D will be hidden, taking [member visibility_range_end_margin] into account as well. The default value of 0 is used to disable the range check. </member> - <member name="visibility_range_end_margin" type="float" setter="set_visibility_range_end_margin" getter="get_visibility_range_end_margin" default="0.0"> + <member name="visibility_range_end_margin" type="float" setter="set_visibility_range_end_margin" getter="get_visibility_range_end_margin" default="0.0" keywords="lod_end_margin, hlod_end_margin"> Margin for the [member visibility_range_end] threshold. The GeometryInstance3D will only change its visibility state when it goes over or under the [member visibility_range_end] threshold by this amount. If [member visibility_range_fade_mode] is [constant VISIBILITY_RANGE_FADE_DISABLED], this acts as a hysteresis distance. If [member visibility_range_fade_mode] is [constant VISIBILITY_RANGE_FADE_SELF] or [constant VISIBILITY_RANGE_FADE_DEPENDENCIES], this acts as a fade transition distance and must be set to a value greater than [code]0.0[/code] for the effect to be noticeable. </member> - <member name="visibility_range_fade_mode" type="int" setter="set_visibility_range_fade_mode" getter="get_visibility_range_fade_mode" enum="GeometryInstance3D.VisibilityRangeFadeMode" default="0"> + <member name="visibility_range_fade_mode" type="int" setter="set_visibility_range_fade_mode" getter="get_visibility_range_fade_mode" enum="GeometryInstance3D.VisibilityRangeFadeMode" default="0" keywords="lod_fade_mode, hlod_fade_mode"> Controls which instances will be faded when approaching the limits of the visibility range. See [enum VisibilityRangeFadeMode] for possible values. </member> </members> @@ -102,13 +102,13 @@ In other words, the actual mesh will not be visible, only the shadows casted from the mesh will be. </constant> <constant name="GI_MODE_DISABLED" value="0" enum="GIMode"> - Disabled global illumination mode. Use for dynamic objects that do not contribute to global illumination (such as characters). When using [VoxelGI] and SDFGI, the geometry will [i]receive[/i] indirect lighting and reflections but the geometry will not be considered in GI baking. When using [LightmapGI], the object will receive indirect lighting using lightmap probes instead of using the baked lightmap texture. + Disabled global illumination mode. Use for dynamic objects that do not contribute to global illumination (such as characters). When using [VoxelGI] and SDFGI, the geometry will [i]receive[/i] indirect lighting and reflections but the geometry will not be considered in GI baking. </constant> <constant name="GI_MODE_STATIC" value="1" enum="GIMode"> Baked global illumination mode. Use for static objects that contribute to global illumination (such as level geometry). This GI mode is effective when using [VoxelGI], SDFGI and [LightmapGI]. </constant> <constant name="GI_MODE_DYNAMIC" value="2" enum="GIMode"> - Dynamic global illumination mode. Use for dynamic objects that contribute to global illumination. This GI mode is only effective when using [VoxelGI], but it has a higher performance impact than [constant GI_MODE_STATIC]. When using other GI methods, this will act the same as [constant GI_MODE_DISABLED]. + Dynamic global illumination mode. Use for dynamic objects that contribute to global illumination. This GI mode is only effective when using [VoxelGI], but it has a higher performance impact than [constant GI_MODE_STATIC]. When using other GI methods, this will act the same as [constant GI_MODE_DISABLED]. When using [LightmapGI], the object will receive indirect lighting using lightmap probes instead of using the baked lightmap texture. </constant> <constant name="LIGHTMAP_SCALE_1X" value="0" enum="LightmapScale"> The standard texel density for lightmapping with [LightmapGI]. diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index 410efd6389..001839d745 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="GraphEdit" inherits="Control" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="GraphEdit" inherits="Control" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> An editor for graph-like structures, using [GraphNode]s. </brief_description> @@ -109,6 +109,14 @@ Rearranges selected nodes in a layout with minimum crossings between connections and uniform horizontal and vertical gap between nodes. </description> </method> + <method name="attach_graph_element_to_frame"> + <return type="void" /> + <param index="0" name="element" type="StringName" /> + <param index="1" name="frame" type="StringName" /> + <description> + Attaches the [param element] [GraphElement] to the [param frame] [GraphFrame]. + </description> + </method> <method name="clear_connections"> <return type="void" /> <description> @@ -125,6 +133,13 @@ Create a connection between the [param from_port] of the [param from_node] [GraphNode] and the [param to_port] of the [param to_node] [GraphNode]. If the connection already exists, no connection is created. </description> </method> + <method name="detach_graph_element_from_frame"> + <return type="void" /> + <param index="0" name="element" type="StringName" /> + <description> + Detaches the [param element] [GraphElement] from the [GraphFrame] it is currently attached to. + </description> + </method> <method name="disconnect_node"> <return type="void" /> <param index="0" name="from_node" type="StringName" /> @@ -143,7 +158,29 @@ [b]Note:[/b] This method suppresses any other connection request signals apart from [signal connection_drag_ended]. </description> </method> - <method name="get_connection_line"> + <method name="get_attached_nodes_of_frame"> + <return type="StringName[]" /> + <param index="0" name="frame" type="StringName" /> + <description> + Returns an array of node names that are attached to the [GraphFrame] with the given name. + </description> + </method> + <method name="get_closest_connection_at_point" qualifiers="const"> + <return type="Dictionary" /> + <param index="0" name="point" type="Vector2" /> + <param index="1" name="max_distance" type="float" default="4.0" /> + <description> + Returns the closest connection to the given point in screen space. If no connection is found within [param max_distance] pixels, an empty [Dictionary] is returned. + A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. + For example, getting a connection at a given mouse position can be achieved like this: + [codeblocks] + [gdscript] + var connection = get_closest_connection_at_point(mouse_event.get_position()) + [/gdscript] + [/codeblocks] + </description> + </method> + <method name="get_connection_line" qualifiers="const"> <return type="PackedVector2Array" /> <param index="0" name="from_node" type="Vector2" /> <param index="1" name="to_node" type="Vector2" /> @@ -154,7 +191,21 @@ <method name="get_connection_list" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns an Array containing the list of connections. A connection consists in a structure of the form [code]{ from_port: 0, from: "GraphNode name 0", to_port: 1, to: "GraphNode name 1" }[/code]. + Returns an [Array] containing the list of connections. A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. + </description> + </method> + <method name="get_connections_intersecting_with_rect" qualifiers="const"> + <return type="Dictionary[]" /> + <param index="0" name="rect" type="Rect2" /> + <description> + Returns an [Array] containing the list of connections that intersect with the given [Rect2]. A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. + </description> + </method> + <method name="get_element_frame"> + <return type="GraphFrame" /> + <param index="0" name="element" type="StringName" /> + <description> + Returns the [GraphFrame] that contains the [GraphElement] with the given name. </description> </method> <method name="get_menu_hbox"> @@ -233,10 +284,13 @@ <member name="connection_lines_curvature" type="float" setter="set_connection_lines_curvature" getter="get_connection_lines_curvature" default="0.5"> The curvature of the lines between the nodes. 0 results in straight lines. </member> - <member name="connection_lines_thickness" type="float" setter="set_connection_lines_thickness" getter="get_connection_lines_thickness" default="2.0"> + <member name="connection_lines_thickness" type="float" setter="set_connection_lines_thickness" getter="get_connection_lines_thickness" default="4.0"> The thickness of the lines between the nodes. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> + <member name="grid_pattern" type="int" setter="set_grid_pattern" getter="get_grid_pattern" enum="GraphEdit.GridPattern" default="0"> + The pattern used for drawing the grid. + </member> <member name="minimap_enabled" type="bool" setter="set_minimap_enabled" getter="is_minimap_enabled" default="true"> If [code]true[/code], the minimap is visible. </member> @@ -298,7 +352,7 @@ <signals> <signal name="begin_node_move"> <description> - Emitted at the beginning of a GraphNode movement. + Emitted at the beginning of a [GraphElement]'s movement. </description> </signal> <signal name="connection_drag_ended"> @@ -341,13 +395,14 @@ </signal> <signal name="copy_nodes_request"> <description> - Emitted when the user presses [kbd]Ctrl + C[/kbd]. + Emitted when this [GraphEdit] captures a [code]ui_copy[/code] action ([kbd]Ctrl + C[/kbd] by default). In general, this signal indicates that the selected [GraphElement]s should be copied. </description> </signal> <signal name="delete_nodes_request"> <param index="0" name="nodes" type="StringName[]" /> <description> - Emitted when attempting to remove a GraphNode from the GraphEdit. Provides a list of node names to be removed (all selected nodes, excluding nodes without closing button). + Emitted when this [GraphEdit] captures a [code]ui_graph_delete[/code] action ([kbd]Delete[/kbd] by default). + [param nodes] is an array of node names that should be removed. These usually include all selected nodes. </description> </signal> <signal name="disconnection_request"> @@ -361,34 +416,50 @@ </signal> <signal name="duplicate_nodes_request"> <description> - Emitted when a GraphNode is attempted to be duplicated in the GraphEdit. + Emitted when this [GraphEdit] captures a [code]ui_graph_duplicate[/code] action ([kbd]Ctrl + D[/kbd] by default). In general, this signal indicates that the selected [GraphElement]s should be duplicated. </description> </signal> <signal name="end_node_move"> <description> - Emitted at the end of a GraphNode movement. + Emitted at the end of a [GraphElement]'s movement. + </description> + </signal> + <signal name="frame_rect_changed"> + <param index="0" name="frame" type="GraphFrame" /> + <param index="1" name="new_rect" type="Vector2" /> + <description> + Emitted when the [GraphFrame] [param frame] is resized to [param new_rect]. + </description> + </signal> + <signal name="graph_elements_linked_to_frame_request"> + <param index="0" name="elements" type="Array" /> + <param index="1" name="frame" type="StringName" /> + <description> + Emitted when one or more [GraphElement]s are dropped onto the [GraphFrame] named [param frame], when they were not previously attached to any other one. + [param elements] is an array of [GraphElement]s to be attached. </description> </signal> <signal name="node_deselected"> <param index="0" name="node" type="Node" /> <description> + Emitted when the given [GraphElement] node is deselected. </description> </signal> <signal name="node_selected"> <param index="0" name="node" type="Node" /> <description> - Emitted when a GraphNode is selected. + Emitted when the given [GraphElement] node is selected. </description> </signal> <signal name="paste_nodes_request"> <description> - Emitted when the user presses [kbd]Ctrl + V[/kbd]. + Emitted when this [GraphEdit] captures a [code]ui_paste[/code] action ([kbd]Ctrl + V[/kbd] by default). In general, this signal indicates that previously copied [GraphElement]s should be pasted. </description> </signal> <signal name="popup_request"> - <param index="0" name="position" type="Vector2" /> + <param index="0" name="at_position" type="Vector2" /> <description> - Emitted when a popup is requested. Happens on right-clicking in the GraphEdit. [param position] is the position of the mouse pointer when the signal is sent. + Emitted when a popup is requested. Happens on right-clicking in the GraphEdit. [param at_position] is the position of the mouse pointer when the signal is sent. </description> </signal> <signal name="scroll_offset_changed"> @@ -405,16 +476,31 @@ <constant name="SCROLL_PANS" value="1" enum="PanningScheme"> [kbd]Mouse Wheel[/kbd] will move the view, [kbd]Ctrl + Mouse Wheel[/kbd] will zoom. </constant> + <constant name="GRID_PATTERN_LINES" value="0" enum="GridPattern"> + Draw the grid using solid lines. + </constant> + <constant name="GRID_PATTERN_DOTS" value="1" enum="GridPattern"> + Draw the grid using dots. + </constant> </constants> <theme_items> <theme_item name="activity" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> - Color of the connection's activity (see [method set_connection_activity]). + Color the connection line is interpolated to based on the activity value of a connection (see [method set_connection_activity]). + </theme_item> + <theme_item name="connection_hover_tint_color" data_type="color" type="Color" default="Color(0, 0, 0, 0.3)"> + Color which is blended with the connection line when the mouse is hovering over it. + </theme_item> + <theme_item name="connection_rim_color" data_type="color" type="Color" default="Color(0.1, 0.1, 0.1, 0.6)"> + Color of the rim around each connection line used for making intersecting lines more distinguishable. + </theme_item> + <theme_item name="connection_valid_target_tint_color" data_type="color" type="Color" default="Color(1, 1, 1, 0.4)"> + Color which is blended with the connection line when the currently dragged connection is hovering over a valid target port. </theme_item> <theme_item name="grid_major" data_type="color" type="Color" default="Color(1, 1, 1, 0.2)"> - Color of major grid lines. + Color of major grid lines/dots. </theme_item> <theme_item name="grid_minor" data_type="color" type="Color" default="Color(1, 1, 1, 0.05)"> - Color of minor grid lines. + Color of minor grid lines/dots. </theme_item> <theme_item name="selection_fill" data_type="color" type="Color" default="Color(1, 1, 1, 0.3)"> The fill color of the selection rectangle. diff --git a/doc/classes/GraphElement.xml b/doc/classes/GraphElement.xml index dd2c7f3d3e..7cd6496773 100644 --- a/doc/classes/GraphElement.xml +++ b/doc/classes/GraphElement.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="GraphElement" inherits="Container" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="GraphElement" inherits="Container" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A container that represents a basic element that can be placed inside a [GraphEdit] control. </brief_description> @@ -17,7 +17,7 @@ </member> <member name="resizable" type="bool" setter="set_resizable" getter="is_resizable" default="false"> If [code]true[/code], the user can resize the GraphElement. - [b]Note:[/b] Dragging the handle will only emit the [signal resize_request] signal, the GraphElement needs to be resized manually. + [b]Note:[/b] Dragging the handle will only emit the [signal resize_request] and [signal resize_end] signals, the GraphElement needs to be resized manually. </member> <member name="selectable" type="bool" setter="set_selectable" getter="is_selectable" default="true"> If [code]true[/code], the user can select the GraphElement. @@ -59,8 +59,14 @@ Emitted when displaying the GraphElement over other ones is requested. Happens on focusing (clicking into) the GraphElement. </description> </signal> + <signal name="resize_end"> + <param index="0" name="new_size" type="Vector2" /> + <description> + Emitted when releasing the mouse button after dragging the resizer handle (see [member resizable]). + </description> + </signal> <signal name="resize_request"> - <param index="0" name="new_minsize" type="Vector2" /> + <param index="0" name="new_size" type="Vector2" /> <description> Emitted when resizing the GraphElement is requested. Happens on dragging the resizer handle (see [member resizable]). </description> diff --git a/doc/classes/GraphFrame.xml b/doc/classes/GraphFrame.xml new file mode 100644 index 0000000000..52bb451d95 --- /dev/null +++ b/doc/classes/GraphFrame.xml @@ -0,0 +1,66 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="GraphFrame" inherits="GraphElement" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + GraphFrame is a special [GraphElement] that can be used to organize other [GraphElement]s inside a [GraphEdit]. + </brief_description> + <description> + GraphFrame is a special [GraphElement] to which other [GraphElement]s can be attached. It can be configured to automatically resize to enclose all attached [GraphElement]s. If the frame is moved, all the attached [GraphElement]s inside it will be moved as well. + A GraphFrame is always kept behind the connection layer and other [GraphElement]s inside a [GraphEdit]. + </description> + <tutorials> + </tutorials> + <methods> + <method name="get_titlebar_hbox"> + <return type="HBoxContainer" /> + <description> + Returns the [HBoxContainer] used for the title bar, only containing a [Label] for displaying the title by default. + This can be used to add custom controls to the title bar such as option or close buttons. + </description> + </method> + </methods> + <members> + <member name="autoshrink_enabled" type="bool" setter="set_autoshrink_enabled" getter="is_autoshrink_enabled" default="true"> + If [code]true[/code], the frame's rect will be adjusted automatically to enclose all attached [GraphElement]s. + </member> + <member name="autoshrink_margin" type="int" setter="set_autoshrink_margin" getter="get_autoshrink_margin" default="40"> + The margin around the attached nodes that is used to calculate the size of the frame when [member autoshrink_enabled] is [code]true[/code]. + </member> + <member name="drag_margin" type="int" setter="set_drag_margin" getter="get_drag_margin" default="16"> + The margin inside the frame that can be used to drag the frame. + </member> + <member name="mouse_filter" type="int" setter="set_mouse_filter" getter="get_mouse_filter" overrides="Control" enum="Control.MouseFilter" default="0" /> + <member name="tint_color" type="Color" setter="set_tint_color" getter="get_tint_color" default="Color(0.3, 0.3, 0.3, 0.75)"> + The color of the frame when [member tint_color_enabled] is [code]true[/code]. + </member> + <member name="tint_color_enabled" type="bool" setter="set_tint_color_enabled" getter="is_tint_color_enabled" default="false"> + If [code]true[/code], the tint color will be used to tint the frame. + </member> + <member name="title" type="String" setter="set_title" getter="get_title" default=""""> + Title of the frame. + </member> + </members> + <signals> + <signal name="autoshrink_changed"> + <description> + Emitted when [member autoshrink_enabled] or [member autoshrink_margin] changes. + </description> + </signal> + </signals> + <theme_items> + <theme_item name="resizer_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)"> + The color modulation applied to the resizer icon. + </theme_item> + <theme_item name="panel" data_type="style" type="StyleBox"> + The default [StyleBox] used for the background of the [GraphFrame]. + </theme_item> + <theme_item name="panel_selected" data_type="style" type="StyleBox"> + The [StyleBox] used for the background of the [GraphFrame] when it is selected. + </theme_item> + <theme_item name="titlebar" data_type="style" type="StyleBox"> + The [StyleBox] used for the title bar of the [GraphFrame]. + </theme_item> + <theme_item name="titlebar_selected" data_type="style" type="StyleBox"> + The [StyleBox] used for the title bar of the [GraphFrame] when it is selected. + </theme_item> + </theme_items> +</class> diff --git a/doc/classes/GraphNode.xml b/doc/classes/GraphNode.xml index 9e1392567a..ad1028d7f4 100644 --- a/doc/classes/GraphNode.xml +++ b/doc/classes/GraphNode.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="GraphNode" inherits="GraphElement" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="GraphNode" inherits="GraphElement" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A container with connection ports, representing a node in a [GraphEdit]. </brief_description> @@ -116,6 +116,20 @@ Returns the right (output) [Color] of the slot with the given [param slot_index]. </description> </method> + <method name="get_slot_custom_icon_left" qualifiers="const"> + <return type="Texture2D" /> + <param index="0" name="slot_index" type="int" /> + <description> + Returns the left (input) custom [Texture2D] of the slot with the given [param slot_index]. + </description> + </method> + <method name="get_slot_custom_icon_right" qualifiers="const"> + <return type="Texture2D" /> + <param index="0" name="slot_index" type="int" /> + <description> + Returns the right (output) custom [Texture2D] of the slot with the given [param slot_index]. + </description> + </method> <method name="get_slot_type_left" qualifiers="const"> <return type="int" /> <param index="0" name="slot_index" type="int" /> @@ -195,6 +209,22 @@ Sets the [Color] of the right (output) side of the slot with the given [param slot_index] to [param color]. </description> </method> + <method name="set_slot_custom_icon_left"> + <return type="void" /> + <param index="0" name="slot_index" type="int" /> + <param index="1" name="custom_icon" type="Texture2D" /> + <description> + Sets the custom [Texture2D] of the left (input) side of the slot with the given [param slot_index] to [param custom_icon]. + </description> + </method> + <method name="set_slot_custom_icon_right"> + <return type="void" /> + <param index="0" name="slot_index" type="int" /> + <param index="1" name="custom_icon" type="Texture2D" /> + <description> + Sets the custom [Texture2D] of the right (output) side of the slot with the given [param slot_index] to [param custom_icon]. + </description> + </method> <method name="set_slot_draw_stylebox"> <return type="void" /> <param index="0" name="slot_index" type="int" /> diff --git a/doc/classes/GridContainer.xml b/doc/classes/GridContainer.xml index cd96bd49d9..d69f4a10d2 100644 --- a/doc/classes/GridContainer.xml +++ b/doc/classes/GridContainer.xml @@ -18,10 +18,10 @@ </members> <theme_items> <theme_item name="h_separation" data_type="constant" type="int" default="4"> - The horizontal separation of children nodes. + The horizontal separation of child nodes. </theme_item> <theme_item name="v_separation" data_type="constant" type="int" default="4"> - The vertical separation of children nodes. + The vertical separation of child nodes. </theme_item> </theme_items> </class> diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index f0385a7814..b6007a3b6b 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -156,9 +156,9 @@ [/gdscript] [csharp] var fields = new Godot.Collections.Dictionary { { "username", "user" }, { "password", "pass" } }; - string queryString = new HTTPClient().QueryStringFromDict(fields); + string queryString = new HttpClient().QueryStringFromDict(fields); string[] headers = { "Content-Type: application/x-www-form-urlencoded", $"Content-Length: {queryString.Length}" }; - var result = new HTTPClient().Request(HTTPClient.Method.Post, "index.php", headers, queryString); + var result = new HttpClient().Request(HttpClient.Method.Post, "index.php", headers, queryString); [/csharp] [/codeblocks] [b]Note:[/b] The [param body] parameter is ignored if [param method] is [constant HTTPClient.METHOD_GET]. This is because GET methods can't contain request data. As a workaround, you can pass request data as a query string in the URL. See [method String.uri_encode] for an example. @@ -322,11 +322,11 @@ <constant name="RESPONSE_NOT_MODIFIED" value="304" enum="ResponseCode"> HTTP status code [code]304 Not Modified[/code]. A conditional GET or HEAD request has been received and would have resulted in a 200 OK response if it were not for the fact that the condition evaluated to [code]false[/code]. </constant> - <constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode" is_deprecated="true"> - [i]Deprecated.[/i] HTTP status code [code]305 Use Proxy[/code]. + <constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode" deprecated="Many clients ignore this response code for security reasons. It is also deprecated by the HTTP standard."> + HTTP status code [code]305 Use Proxy[/code]. </constant> - <constant name="RESPONSE_SWITCH_PROXY" value="306" enum="ResponseCode" is_deprecated="true"> - [i]Deprecated.[/i] HTTP status code [code]306 Switch Proxy[/code]. + <constant name="RESPONSE_SWITCH_PROXY" value="306" enum="ResponseCode" deprecated="Many clients ignore this response code for security reasons. It is also deprecated by the HTTP standard."> + HTTP status code [code]306 Switch Proxy[/code]. </constant> <constant name="RESPONSE_TEMPORARY_REDIRECT" value="307" enum="ResponseCode"> HTTP status code [code]307 Temporary Redirect[/code]. The target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml index 03c1ce2e00..6efa675a71 100644 --- a/doc/classes/HTTPRequest.xml +++ b/doc/classes/HTTPRequest.xml @@ -43,7 +43,7 @@ public override void _Ready() { // Create an HTTP request node and connect its completion signal. - var httpRequest = new HTTPRequest(); + var httpRequest = new HttpRequest(); AddChild(httpRequest); httpRequest.RequestCompleted += HttpRequestCompleted; @@ -61,7 +61,7 @@ { { "name", "Godette" } }); - error = httpRequest.Request("https://httpbin.org/post", null, HTTPClient.Method.Post, body); + error = httpRequest.Request("https://httpbin.org/post", null, HttpClient.Method.Post, body); if (error != Error.Ok) { GD.PushError("An error occurred in the HTTP request."); @@ -115,7 +115,7 @@ public override void _Ready() { // Create an HTTP request node and connect its completion signal. - var httpRequest = new HTTPRequest(); + var httpRequest = new HttpRequest(); AddChild(httpRequest); httpRequest.RequestCompleted += HttpRequestCompleted; @@ -130,7 +130,7 @@ // Called when the HTTP request is completed. private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body) { - if (result != (long)HTTPRequest.Result.Success) + if (result != (long)HttpRequest.Result.Success) { GD.PushError("Image couldn't be downloaded. Try a different image."); } diff --git a/doc/classes/HashingContext.xml b/doc/classes/HashingContext.xml index 86d69bc2f7..f2681ae7b3 100644 --- a/doc/classes/HashingContext.xml +++ b/doc/classes/HashingContext.xml @@ -14,7 +14,7 @@ # Check that file exists. if not FileAccess.file_exists(path): return - # Start a SHA-256 context. + # Start an SHA-256 context. var ctx = HashingContext.new() ctx.start(HashingContext.HASH_SHA256) # Open the file to hash. @@ -37,7 +37,7 @@ { return; } - // Start a SHA-256 context. + // Start an SHA-256 context. var ctx = new HashingContext(); ctx.Start(HashingContext.HashType.Sha256); // Open the file to hash. @@ -68,7 +68,7 @@ <return type="int" enum="Error" /> <param index="0" name="type" type="int" enum="HashingContext.HashType" /> <description> - Starts a new hash computation of the given [param type] (e.g. [constant HASH_SHA256] to start computation of a SHA-256). + Starts a new hash computation of the given [param type] (e.g. [constant HASH_SHA256] to start computation of an SHA-256). </description> </method> <method name="update"> diff --git a/doc/classes/HeightMapShape3D.xml b/doc/classes/HeightMapShape3D.xml index ff120fa557..7e3055b34e 100644 --- a/doc/classes/HeightMapShape3D.xml +++ b/doc/classes/HeightMapShape3D.xml @@ -6,12 +6,50 @@ <description> A 3D heightmap shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape3D]. This is useful for terrain, but it is limited as overhangs (such as caves) cannot be stored. Holes in a [HeightMapShape3D] are created by assigning very low values to points in the desired area. [b]Performance:[/b] [HeightMapShape3D] is faster to check collisions against than [ConcavePolygonShape3D], but it is significantly slower than primitive shapes like [BoxShape3D]. + A heightmap collision shape can also be build by using an [Image] reference: + [codeblocks] + [gdscript] + var heightmap_texture: Texture = ResourceLoader.load("res://heightmap_image.exr") + var heightmap_image: Image = heightmap_texture.get_image() + heightmap_image.convert(Image.FORMAT_RF) + + var height_min: float = 0.0 + var height_max: float = 10.0 + + update_map_data_from_image(heightmap_image, height_min, height_max) + [/gdscript] + [/codeblocks] </description> <tutorials> </tutorials> + <methods> + <method name="get_max_height" qualifiers="const"> + <return type="float" /> + <description> + Returns the largest height value found in [member map_data]. Recalculates only when [member map_data] changes. + </description> + </method> + <method name="get_min_height" qualifiers="const"> + <return type="float" /> + <description> + Returns the smallest height value found in [member map_data]. Recalculates only when [member map_data] changes. + </description> + </method> + <method name="update_map_data_from_image"> + <return type="void" /> + <param index="0" name="image" type="Image" /> + <param index="1" name="height_min" type="float" /> + <param index="2" name="height_max" type="float" /> + <description> + Updates [member map_data] with data read from an [Image] reference. Automatically resizes heightmap [member map_width] and [member map_depth] to fit the full image width and height. + The image needs to be in either [constant Image.FORMAT_RF] (32 bit), [constant Image.FORMAT_RH] (16 bit), or [constant Image.FORMAT_R8] (8 bit). + Each image pixel is read in as a float on the range from [code]0.0[/code] (black pixel) to [code]1.0[/code] (white pixel). This range value gets remapped to [param height_min] and [param height_max] to form the final height value. + </description> + </method> + </methods> <members> <member name="map_data" type="PackedFloat32Array" setter="set_map_data" getter="get_map_data" default="PackedFloat32Array(0, 0, 0, 0)"> - Height map data, pool array must be of [member map_width] * [member map_depth] size. + Height map data. The array's size must be equal to [member map_width] multiplied by [member map_depth]. </member> <member name="map_depth" type="int" setter="set_map_depth" getter="get_map_depth" default="2"> Number of vertices in the depth of the height map. Changing this will resize the [member map_data]. diff --git a/doc/classes/IP.xml b/doc/classes/IP.xml index 9fe3362e0f..129a181614 100644 --- a/doc/classes/IP.xml +++ b/doc/classes/IP.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="IP" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="IP" inherits="Object" keywords="dns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Internet protocol (IP) support functions such as DNS resolution. </brief_description> @@ -65,7 +65,7 @@ Returns a queued hostname's status as a [enum ResolverStatus] constant, given its queue [param id]. </description> </method> - <method name="resolve_hostname"> + <method name="resolve_hostname" keywords="dns"> <return type="String" /> <param index="0" name="host" type="String" /> <param index="1" name="ip_type" type="int" enum="IP.Type" default="3" /> diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 310dae6c65..68d4deaffd 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -10,6 +10,7 @@ </description> <tutorials> <link title="Importing images">$DOCS_URL/tutorials/assets_pipeline/importing_images.html</link> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="adjust_bcs"> @@ -18,6 +19,7 @@ <param index="1" name="contrast" type="float" /> <param index="2" name="saturation" type="float" /> <description> + Adjusts this image's [param brightness], [param contrast], and [param saturation] by the given values. Does not work if the image is compressed (see [method is_compressed]). </description> </method> <method name="blend_rect"> @@ -162,6 +164,7 @@ <return type="int" enum="Image.UsedChannels" /> <param index="0" name="source" type="int" enum="Image.CompressSource" default="0" /> <description> + Returns the color channels used by this image, as one of the [enum UsedChannels] constants. If the image is compressed, the original [param source] must be specified. </description> </method> <method name="fill"> @@ -201,8 +204,8 @@ <return type="int" enum="Error" /> <param index="0" name="renormalize" type="bool" default="false" /> <description> - Generates mipmaps for the image. Mipmaps are precalculated lower-resolution copies of the image that are automatically used if the image needs to be scaled down when rendered. They help improve image quality and performance when rendering. This method returns an error if the image is compressed, in a custom format, or if the image's width/height is [code]0[/code]. Enabling [param renormalize] when generating mipmaps for normal textures will make sure all resulting vector values are normalized. - It is possible to check if the image has mipmaps by calling [method has_mipmaps] or [method get_mipmap_count]. + Generates mipmaps for the image. Mipmaps are precalculated lower-resolution copies of the image that are automatically used if the image needs to be scaled down when rendered. They help improve image quality and performance when rendering. This method returns an error if the image is compressed, in a custom format, or if the image's width/height is [code]0[/code]. Enabling [param renormalize] when generating mipmaps for normal map textures will make sure all resulting vector values are normalized. + It is possible to check if the image has mipmaps by calling [method has_mipmaps] or [method get_mipmap_count]. Calling [method generate_mipmaps] on an image that already has mipmaps will replace existing mipmaps in the image. </description> </method> <method name="get_data" qualifiers="const"> @@ -317,6 +320,7 @@ <description> Loads an image from the binary contents of a BMP file. [b]Note:[/b] Godot's BMP module doesn't support 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported. + [b]Note:[/b] This method is only available in engine builds with the BMP module enabled. By default, the BMP module is enabled, but it can be disabled at build-time using the [code]module_bmp_enabled=no[/code] SCons option. </description> </method> <method name="load_from_file" qualifiers="static"> @@ -337,7 +341,9 @@ <return type="int" enum="Error" /> <param index="0" name="buffer" type="PackedByteArray" /> <description> - Loads an image from the binary contents of a KTX file. + Loads an image from the binary contents of a [url=https://github.com/KhronosGroup/KTX-Software]KTX[/url] file. Unlike most image formats, KTX can store VRAM-compressed data and embed mipmaps. + [b]Note:[/b] Godot's libktx implementation only supports 2D images. Cubemaps, texture arrays, and de-padding are not supported. + [b]Note:[/b] This method is only available in engine builds with the KTX module enabled. By default, the KTX module is enabled, but it can be disabled at build-time using the [code]module_ktx_enabled=no[/code] SCons option. </description> </method> <method name="load_png_from_buffer"> @@ -362,7 +368,7 @@ <param index="0" name="svg_str" type="String" /> <param index="1" name="scale" type="float" default="1.0" /> <description> - Loads an image from the string contents of a SVG file ([b].svg[/b]). + Loads an image from the string contents of an SVG file ([b].svg[/b]). [b]Note:[/b] This method is only available in engine builds with the SVG module enabled. By default, the SVG module is enabled, but it can be disabled at build-time using the [code]module_svg_enabled=no[/code] SCons option. </description> </method> @@ -371,6 +377,7 @@ <param index="0" name="buffer" type="PackedByteArray" /> <description> Loads an image from the binary contents of a TGA file. + [b]Note:[/b] This method is only available in engine builds with the TGA module enabled. By default, the TGA module is enabled, but it can be disabled at build-time using the [code]module_tga_enabled=no[/code] SCons option. </description> </method> <method name="load_webp_from_buffer"> @@ -389,7 +396,7 @@ <method name="premultiply_alpha"> <return type="void" /> <description> - Multiplies color values with alpha values. Resulting color values for a pixel are [code](color * alpha)/256[/code]. + Multiplies color values with alpha values. Resulting color values for a pixel are [code](color * alpha)/256[/code]. See also [member CanvasItemMaterial.blend_mode]. </description> </method> <method name="resize"> @@ -481,7 +488,8 @@ <param index="1" name="lossy" type="bool" default="false" /> <param index="2" name="quality" type="float" default="0.75" /> <description> - Saves the image as a WebP (Web Picture) file to the file at [param path]. By default it will save lossless. If [param lossy] is true, the image will be saved lossy, using the [param quality] setting between 0.0 and 1.0 (inclusive). + Saves the image as a WebP (Web Picture) file to the file at [param path]. By default it will save lossless. If [param lossy] is true, the image will be saved lossy, using the [param quality] setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG. + [b]Note:[/b] The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images. </description> </method> <method name="save_webp_to_buffer" qualifiers="const"> @@ -489,7 +497,8 @@ <param index="0" name="lossy" type="bool" default="false" /> <param index="1" name="quality" type="float" default="0.75" /> <description> - Saves the image as a WebP (Web Picture) file to a byte array. By default it will save lossless. If [param lossy] is true, the image will be saved lossy, using the [param quality] setting between 0.0 and 1.0 (inclusive). + Saves the image as a WebP (Web Picture) file to a byte array. By default it will save lossless. If [param lossy] is true, the image will be saved lossy, using the [param quality] setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG. + [b]Note:[/b] The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images. </description> </method> <method name="set_data"> @@ -559,7 +568,7 @@ <method name="shrink_x2"> <return type="void" /> <description> - Shrinks the image by a factor of 2. + Shrinks the image by a factor of 2 on each axis (this divides the pixel count by 4). </description> </method> <method name="srgb_to_linear"> @@ -605,6 +614,7 @@ OpenGL texture format [code]RGBA[/code] with four components, each with a bitdepth of 4. </constant> <constant name="FORMAT_RGB565" value="7" enum="Format"> + OpenGL texture format [code]RGB[/code] with three components. Red and blue have a bitdepth of 5, and green has a bitdepth of 6. </constant> <constant name="FORMAT_RF" value="8" enum="Format"> OpenGL texture format [code]GL_R32F[/code] where there's one component, a 32-bit floating-point value. @@ -689,17 +699,19 @@ [b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed. </constant> <constant name="FORMAT_ETC2_RA_AS_RG" value="33" enum="Format"> + [url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC2_and_EAC]Ericsson Texture Compression format 2[/url] ([code]RGBA8[/code] variant), which compresses RA data and interprets it as two channels (red and green). See also [constant FORMAT_ETC2_RGBA8]. </constant> <constant name="FORMAT_DXT5_RA_AS_RG" value="34" enum="Format"> + The [url=https://en.wikipedia.org/wiki/S3_Texture_Compression]S3TC[/url] texture format also known as Block Compression 3 or BC3, which compresses RA data and interprets it as two channels (red and green). See also [constant FORMAT_DXT5]. </constant> <constant name="FORMAT_ASTC_4x4" value="35" enum="Format"> - [url=https://en.wikipedia.org/wiki/Adaptive_scalable_texture_compression]Adaptive Scalable Texture Compression[/url]. This implements the 4x4 (high quality) mode. + [url=https://en.wikipedia.org/wiki/Adaptive_scalable_texture_compression]Adaptive Scalable Texture Compression[/url]. This implements the 4×4 (high quality) mode. </constant> <constant name="FORMAT_ASTC_4x4_HDR" value="36" enum="Format"> Same format as [constant FORMAT_ASTC_4x4], but with the hint to let the GPU know it is used for HDR. </constant> <constant name="FORMAT_ASTC_8x8" value="37" enum="Format"> - [url=https://en.wikipedia.org/wiki/Adaptive_scalable_texture_compression]Adaptive Scalable Texture Compression[/url]. This implements the 8x8 (low quality) mode. + [url=https://en.wikipedia.org/wiki/Adaptive_scalable_texture_compression]Adaptive Scalable Texture Compression[/url]. This implements the 8×8 (low quality) mode. </constant> <constant name="FORMAT_ASTC_8x8_HDR" value="38" enum="Format"> Same format as [constant FORMAT_ASTC_8x8], but with the hint to let the GPU know it is used for HDR. @@ -724,7 +736,7 @@ On the other hand, if the image already has mipmaps, they will be used, and a new set will be generated for the resulting image. </constant> <constant name="INTERPOLATE_LANCZOS" value="4" enum="Interpolation"> - Performs Lanczos interpolation. This is the slowest image resizing mode, but it typically gives the best results, especially when downscalng images. + Performs Lanczos interpolation. This is the slowest image resizing mode, but it typically gives the best results, especially when downscaling images. </constant> <constant name="ALPHA_NONE" value="0" enum="AlphaMode"> Image does not have alpha. @@ -754,16 +766,22 @@ Represents the size of the [enum CompressMode] enum. </constant> <constant name="USED_CHANNELS_L" value="0" enum="UsedChannels"> + The image only uses one channel for luminance (grayscale). </constant> <constant name="USED_CHANNELS_LA" value="1" enum="UsedChannels"> + The image uses two channels for luminance and alpha, respectively. </constant> <constant name="USED_CHANNELS_R" value="2" enum="UsedChannels"> + The image only uses the red channel. </constant> <constant name="USED_CHANNELS_RG" value="3" enum="UsedChannels"> + The image uses two channels for red and green. </constant> <constant name="USED_CHANNELS_RGB" value="4" enum="UsedChannels"> + The image uses three channels for red, green, and blue. </constant> <constant name="USED_CHANNELS_RGBA" value="5" enum="UsedChannels"> + The image uses four channels for red, green, blue, and alpha. </constant> <constant name="COMPRESS_SOURCE_GENERIC" value="0" enum="CompressSource"> Source texture (before compression) is a regular texture. Default for all textures. @@ -775,10 +793,10 @@ Source texture (before compression) is a normal texture (e.g. it can be compressed into two channels). </constant> <constant name="ASTC_FORMAT_4x4" value="0" enum="ASTCFormat"> - Hint to indicate that the high quality 4x4 ASTC compression format should be used. + Hint to indicate that the high quality 4×4 ASTC compression format should be used. </constant> <constant name="ASTC_FORMAT_8x8" value="1" enum="ASTCFormat"> - Hint to indicate that the low quality 8x8 ASTC compression format should be used. + Hint to indicate that the low quality 8×8 ASTC compression format should be used. </constant> </constants> </class> diff --git a/doc/classes/ImporterMesh.xml b/doc/classes/ImporterMesh.xml index 9bc1bf035e..eeabcd6e12 100644 --- a/doc/classes/ImporterMesh.xml +++ b/doc/classes/ImporterMesh.xml @@ -31,7 +31,7 @@ Surfaces are created to be rendered using a [param primitive], which may be any of the values defined in [enum Mesh.PrimitiveType]. The [param arrays] argument is an array of arrays. Each of the [constant Mesh.ARRAY_MAX] elements contains an array with some of the mesh data for this surface as described by the corresponding member of [enum Mesh.ArrayType] or [code]null[/code] if it is not used by the surface. For example, [code]arrays[0][/code] is the array of vertices. That first vertex sub-array is always required; the others are optional. Adding an index array puts this surface into "index mode" where the vertex and other arrays become the sources of data and the index array defines the vertex order. All sub-arrays must have the same length as the vertex array (or be an exact multiple of the vertex array's length, when multiple elements of a sub-array correspond to a single vertex) or be empty, except for [constant Mesh.ARRAY_INDEX] if it is used. The [param blend_shapes] argument is an array of vertex data for each blend shape. Each element is an array of the same structure as [param arrays], but [constant Mesh.ARRAY_VERTEX], [constant Mesh.ARRAY_NORMAL], and [constant Mesh.ARRAY_TANGENT] are set if and only if they are set in [param arrays] and all other entries are [code]null[/code]. - The [param lods] argument is a dictionary with [float] keys and [PackedInt32Array] values. Each entry in the dictionary represents a LOD level of the surface, where the value is the [constant Mesh.ARRAY_INDEX] array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of a LOD also increases the distance that the objects has to be from the camera before the LOD is used. + The [param lods] argument is a dictionary with [float] keys and [PackedInt32Array] values. Each entry in the dictionary represents an LOD level of the surface, where the value is the [constant Mesh.ARRAY_INDEX] array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used. The [param flags] argument is the bitwise or of, as required: One value of [enum Mesh.ArrayCustomFormat] left shifted by [code]ARRAY_FORMAT_CUSTOMn_SHIFT[/code] for each custom channel in use, [constant Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE], [constant Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS], or [constant Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY]. [b]Note:[/b] When using indices, it is recommended to only use points, lines, or triangles. </description> diff --git a/doc/classes/Input.xml b/doc/classes/Input.xml index 334b04a79c..e622a6bce3 100644 --- a/doc/classes/Input.xml +++ b/doc/classes/Input.xml @@ -118,7 +118,7 @@ <return type="String" /> <param index="0" name="device" type="int" /> <description> - Returns a SDL2-compatible device GUID on platforms that use gamepad remapping, e.g. [code]030000004c050000c405000000010000[/code]. Returns [code]"Default Gamepad"[/code] otherwise. Godot uses the [url=https://github.com/gabomdq/SDL_GameControllerDB]SDL2 game controller database[/url] to determine gamepad names and mappings based on this GUID. + Returns an SDL2-compatible device GUID on platforms that use gamepad remapping, e.g. [code]030000004c050000c405000000010000[/code]. Returns [code]"Default Gamepad"[/code] otherwise. Godot uses the [url=https://github.com/gabomdq/SDL_GameControllerDB]SDL2 game controller database[/url] to determine gamepad names and mappings based on this GUID. </description> </method> <method name="get_joy_info" qualifiers="const"> @@ -156,6 +156,12 @@ Returns the strength of the joypad vibration: x is the strength of the weak motor, and y is the strength of the strong motor. </description> </method> + <method name="get_last_mouse_screen_velocity"> + <return type="Vector2" /> + <description> + Returns the last mouse velocity in screen coordinates. To provide a precise and jitter-free velocity, mouse velocity is only calculated every 0.1s. Therefore, mouse velocity will lag mouse movements. + </description> + </method> <method name="get_last_mouse_velocity"> <return type="Vector2" /> <description> @@ -228,7 +234,7 @@ Returns [code]true[/code] if any action, key, joypad button, or mouse button is being pressed. This will also return [code]true[/code] if any action is simulated via code by calling [method action_press]. </description> </method> - <method name="is_joy_button_pressed" qualifiers="const"> + <method name="is_joy_button_pressed" qualifiers="const" keywords="is_gamepad_button_pressed, is_controller_button_pressed"> <return type="bool" /> <param index="0" name="device" type="int" /> <param index="1" name="button" type="int" enum="JoyButton" /> @@ -236,7 +242,7 @@ Returns [code]true[/code] if you are pressing the joypad button (see [enum JoyButton]). </description> </method> - <method name="is_joy_known"> + <method name="is_joy_known" keywords="is_gamepad_known, is_controller_known"> <return type="bool" /> <param index="0" name="device" type="int" /> <description> @@ -295,6 +301,7 @@ Input.ParseInputEvent(cancelEvent); [/csharp] [/codeblocks] + [b]Note:[/b] Calling this function has no influence on the operating system. So for example sending an [InputEventMouseMotion] will not move the OS mouse cursor to the specified position (use [method warp_mouse] instead) and sending [kbd]Alt/Cmd + Tab[/kbd] as [InputEventKey] won't toggle between active windows. </description> </method> <method name="remove_joy_mapping"> @@ -319,7 +326,7 @@ <param index="2" name="hotspot" type="Vector2" default="Vector2(0, 0)" /> <description> Sets a custom mouse cursor image, which is only visible inside the game window. The hotspot can also be specified. Passing [code]null[/code] to the image parameter resets to the system cursor. See [enum CursorShape] for the list of shapes. - [param image]'s size must be lower than or equal to 256×256. To avoid rendering issues, sizes lower than or equal to 128×128 are recommended. + [param image] can be either [Texture2D] or [Image] and its size must be lower than or equal to 256×256. To avoid rendering issues, sizes lower than or equal to 128×128 are recommended. [param hotspot] must be within [param image]'s size. [b]Note:[/b] [AnimatedTexture]s aren't supported as custom mouse cursors. If using an [AnimatedTexture], only the first frame will be displayed. [b]Note:[/b] The [b]Lossless[/b], [b]Lossy[/b] or [b]Uncompressed[/b] compression modes are recommended. The [b]Video RAM[/b] compression mode can be used, but it will be decompressed on the CPU, which means loading times are slowed down and no memory is saved compared to lossless modes. @@ -377,6 +384,7 @@ <description> Starts to vibrate the joypad. Joypads usually come with two rumble motors, a strong and a weak one. [param weak_magnitude] is the strength of the weak motor (between 0 and 1) and [param strong_magnitude] is the strength of the strong motor (between 0 and 1). [param duration] is the duration of the effect in seconds (a duration of 0 will try to play the vibration indefinitely). The vibration can be stopped early by calling [method stop_joy_vibration]. [b]Note:[/b] Not every hardware is compatible with long effect durations; it is recommended to restart an effect if it has to be played for more than a few seconds. + [b]Note:[/b] For macOS, vibration is only supported in macOS 11 and later. </description> </method> <method name="stop_joy_vibration"> @@ -408,6 +416,12 @@ </method> </methods> <members> + <member name="emulate_mouse_from_touch" type="bool" setter="set_emulate_mouse_from_touch" getter="is_emulating_mouse_from_touch"> + If [code]true[/code], sends mouse input events when tapping or swiping on the touchscreen. See also [member ProjectSettings.input_devices/pointing/emulate_mouse_from_touch]. + </member> + <member name="emulate_touch_from_mouse" type="bool" setter="set_emulate_touch_from_mouse" getter="is_emulating_touch_from_mouse"> + If [code]true[/code], sends touch input events when clicking or dragging the mouse. See also [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse]. + </member> <member name="mouse_mode" type="int" setter="set_mouse_mode" getter="get_mouse_mode" enum="Input.MouseMode"> Controls the mouse mode. See [enum MouseMode] for more information. </member> @@ -456,10 +470,10 @@ Cross cursor. Typically appears over regions in which a drawing operation can be performed or for selections. </constant> <constant name="CURSOR_WAIT" value="4" enum="CursorShape"> - Wait cursor. Indicates that the application is busy performing an operation. This cursor shape denotes that the application isn't usable during the operation (e.g. something is blocking its main thread). + Wait cursor. Indicates that the application is busy performing an operation, and that it cannot be used during the operation (e.g. something is blocking its main thread). </constant> <constant name="CURSOR_BUSY" value="5" enum="CursorShape"> - Busy cursor. Indicates that the application is busy performing an operation. This cursor shape denotes that the application is still usable during the operation. + Busy cursor. Indicates that the application is busy performing an operation, and that it is still usable during the operation. </constant> <constant name="CURSOR_DRAG" value="6" enum="CursorShape"> Drag cursor. Usually displayed when dragging something. diff --git a/doc/classes/InputEvent.xml b/doc/classes/InputEvent.xml index 391d060fc3..96a4612466 100644 --- a/doc/classes/InputEvent.xml +++ b/doc/classes/InputEvent.xml @@ -117,7 +117,12 @@ <members> <member name="device" type="int" setter="set_device" getter="get_device" default="0"> The event's device ID. - [b]Note:[/b] This device ID will always be [code]-1[/code] for emulated mouse input from a touchscreen. This can be used to distinguish emulated mouse input from physical mouse input. + [b]Note:[/b] [member device] can be negative for special use cases that don't refer to devices physically present on the system. See [constant DEVICE_ID_EMULATION]. </member> </members> + <constants> + <constant name="DEVICE_ID_EMULATION" value="-1"> + Device ID used for emulated mouse input from a touchscreen, or for emulated touch input from a mouse. This can be used to distinguish emulated mouse input from physical mouse input, or emulated touch input from physical touch input. + </constant> + </constants> </class> diff --git a/doc/classes/InputEventJoypadButton.xml b/doc/classes/InputEventJoypadButton.xml index 4a1ecb962c..3d1842fa77 100644 --- a/doc/classes/InputEventJoypadButton.xml +++ b/doc/classes/InputEventJoypadButton.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="InputEventJoypadButton" inherits="InputEvent" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="InputEventJoypadButton" inherits="InputEvent" keywords="gamepad, controller" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Represents a gamepad button being pressed or released. </brief_description> @@ -16,8 +16,7 @@ <member name="pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false"> If [code]true[/code], the button's state is pressed. If [code]false[/code], the button's state is released. </member> - <member name="pressure" type="float" setter="set_pressure" getter="get_pressure" default="0.0"> - Represents the pressure the user puts on the button with their finger, if the controller supports it. Ranges from [code]0[/code] to [code]1[/code]. + <member name="pressure" type="float" setter="set_pressure" getter="get_pressure" default="0.0" deprecated="This property is never set by the engine and is always [code]0[/code]."> </member> </members> </class> diff --git a/doc/classes/InputEventJoypadMotion.xml b/doc/classes/InputEventJoypadMotion.xml index f6b9692d38..ab939874e5 100644 --- a/doc/classes/InputEventJoypadMotion.xml +++ b/doc/classes/InputEventJoypadMotion.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="InputEventJoypadMotion" inherits="InputEvent" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="InputEventJoypadMotion" inherits="InputEvent" keywords="gamepad, controller" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Represents axis motions (such as joystick or analog triggers) from a gamepad. </brief_description> diff --git a/doc/classes/InputEventKey.xml b/doc/classes/InputEventKey.xml index 48a6804290..7b6fc3f216 100644 --- a/doc/classes/InputEventKey.xml +++ b/doc/classes/InputEventKey.xml @@ -24,6 +24,12 @@ Returns a [String] representation of the event's [member keycode] and modifiers. </description> </method> + <method name="as_text_location" qualifiers="const"> + <return type="String" /> + <description> + Returns a [String] representation of the event's [member location]. This will be a blank string if the event is not specific to a location. + </description> + </method> <method name="as_text_physical_keycode" qualifiers="const"> <return type="String" /> <description> @@ -77,6 +83,9 @@ +-----+ +-----+ [/codeblock] </member> + <member name="location" type="int" setter="set_location" getter="get_location" enum="KeyLocation" default="0"> + Represents the location of a key which has both left and right versions, such as [kbd]Shift[/kbd] or [kbd]Alt[/kbd]. + </member> <member name="physical_keycode" type="int" setter="set_physical_keycode" getter="get_physical_keycode" enum="Key" default="0"> Represents the physical location of a key on the 101/102-key US QWERTY keyboard, which corresponds to one of the [enum Key] constants. To get a human-readable representation of the [InputEventKey], use [method OS.get_keycode_string] in combination with [method DisplayServer.keyboard_get_keycode_from_physical]: diff --git a/doc/classes/InputEventMIDI.xml b/doc/classes/InputEventMIDI.xml index d685fdfa41..4dcaf98747 100644 --- a/doc/classes/InputEventMIDI.xml +++ b/doc/classes/InputEventMIDI.xml @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="InputEventMIDI" inherits="InputEvent" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Represents an input event from a MIDI device, such as a piano. + Represents a MIDI message from a MIDI device, such as a musical keyboard. </brief_description> <description> - InputEventMIDI allows receiving input events from MIDI (Musical Instrument Digital Interface) devices such as a piano. - MIDI signals can be sent over a 5-pin MIDI connector or over USB, if your device supports both be sure to check the settings in the device to see which output it's using. - To receive input events from MIDI devices, you need to call [method OS.open_midi_inputs]. You can check which devices are detected using [method OS.get_connected_midi_inputs]. + InputEventMIDI stores information about messages from [url=https://en.wikipedia.org/wiki/MIDI]MIDI[/url] (Musical Instrument Digital Interface) devices. These may include musical keyboards, synthesizers, and drum machines. + MIDI messages can be received over a 5-pin MIDI connector or over USB. If your device supports both be sure to check the settings in the device to see which output it is using. + By default, Godot does not detect MIDI devices. You need to call [method OS.open_midi_inputs], first. You can check which devices are detected with [method OS.get_connected_midi_inputs], and close the connection with [method OS.close_midi_inputs]. [codeblocks] [gdscript] func _ready(): @@ -17,16 +17,16 @@ if input_event is InputEventMIDI: _print_midi_info(input_event) - func _print_midi_info(midi_event: InputEventMIDI): + func _print_midi_info(midi_event): print(midi_event) - print("Channel " + str(midi_event.channel)) - print("Message " + str(midi_event.message)) - print("Pitch " + str(midi_event.pitch)) - print("Velocity " + str(midi_event.velocity)) - print("Instrument " + str(midi_event.instrument)) - print("Pressure " + str(midi_event.pressure)) - print("Controller number: " + str(midi_event.controller_number)) - print("Controller value: " + str(midi_event.controller_value)) + print("Channel ", midi_event.channel) + print("Message ", midi_event.message) + print("Pitch ", midi_event.pitch) + print("Velocity ", midi_event.velocity) + print("Instrument ", midi_event.instrument) + print("Pressure ", midi_event.pressure) + print("Controller number: ", midi_event.controller_number) + print("Controller value: ", midi_event.controller_value) [/gdscript] [csharp] public override void _Ready() @@ -35,15 +35,15 @@ GD.Print(OS.GetConnectedMidiInputs()); } - public override void _Input(InputEvent @event) + public override void _Input(InputEvent inputEvent) { - if (@event is InputEventMIDI midiEvent) + if (inputEvent is InputEventMidi midiEvent) { PrintMIDIInfo(midiEvent); } } - private void PrintMIDIInfo(InputEventMIDI midiEvent) + private void PrintMIDIInfo(InputEventMidi midiEvent) { GD.Print(midiEvent); GD.Print($"Channel {midiEvent.Channel}"); @@ -57,7 +57,7 @@ } [/csharp] [/codeblocks] - Note that Godot does not currently support MIDI output, so there is no way to emit MIDI signals from Godot. Only MIDI input works. + [b]Note:[/b] Godot does not support MIDI output, so there is no way to emit MIDI messages from Godot. Only MIDI input is supported. </description> <tutorials> <link title="MIDI Message Status Byte List">https://www.midi.org/specifications-old/item/table-2-expanded-messages-list-status-bytes</link> @@ -66,33 +66,39 @@ </tutorials> <members> <member name="channel" type="int" setter="set_channel" getter="get_channel" default="0"> - The MIDI channel of this input event. There are 16 channels, so this value ranges from 0 to 15. MIDI channel 9 is reserved for the use with percussion instruments, the rest of the channels are for non-percussion instruments. + The MIDI channel of this message, ranging from [code]0[/code] to [code]15[/code]. MIDI channel [code]9[/code] is reserved for percussion instruments. </member> <member name="controller_number" type="int" setter="set_controller_number" getter="get_controller_number" default="0"> - If the message is [constant MIDI_MESSAGE_CONTROL_CHANGE], this indicates the controller number, otherwise this is zero. Controllers include devices such as pedals and levers. + The unique number of the controller, if [member message] is [constant MIDI_MESSAGE_CONTROL_CHANGE], otherwise this is [code]0[/code]. This value can be used to identify sliders for volume, balance, and panning, as well as switches and pedals on the MIDI device. See the [url=https://en.wikipedia.org/wiki/General_MIDI#Controller_events]General MIDI specification[/url] for a small list. </member> <member name="controller_value" type="int" setter="set_controller_value" getter="get_controller_value" default="0"> - If the message is [constant MIDI_MESSAGE_CONTROL_CHANGE], this indicates the controller value, otherwise this is zero. Controllers include devices such as pedals and levers. + The value applied to the controller. If [member message] is [constant MIDI_MESSAGE_CONTROL_CHANGE], this value ranges from [code]0[/code] to [code]127[/code], otherwise it is [code]0[/code]. See also [member controller_value]. </member> <member name="instrument" type="int" setter="set_instrument" getter="get_instrument" default="0"> - The instrument of this input event. This value ranges from 0 to 127. Refer to the instrument list on the General MIDI wikipedia article to see a list of instruments, except that this value is 0-index, so subtract one from every number on that chart. A standard piano will have an instrument number of 0. + The instrument (also called [i]program[/i] or [i]preset[/i]) used on this MIDI message. This value ranges from [code]0[/code] to [code]127[/code]. + To see what each value means, refer to the [url=https://en.wikipedia.org/wiki/General_MIDI#Program_change_events]General MIDI's instrument list[/url]. Keep in mind that the list is off by 1 because it does not begin from 0. A value of [code]0[/code] corresponds to the acoustic grand piano. </member> <member name="message" type="int" setter="set_message" getter="get_message" enum="MIDIMessage" default="0"> - Returns a value indicating the type of message for this MIDI signal. This is a member of the [enum MIDIMessage] enum. - For MIDI messages between 0x80 and 0xEF, only the left half of the bits are returned as this value, as the other part is the channel (ex: 0x94 becomes 0x9). For MIDI messages from 0xF0 to 0xFF, the value is returned as-is. - Notes will return [constant MIDI_MESSAGE_NOTE_ON] when activated, but they might not always return [constant MIDI_MESSAGE_NOTE_OFF] when deactivated, therefore your code should treat the input as stopped if some period of time has passed. - Some MIDI devices may send [constant MIDI_MESSAGE_NOTE_ON] with zero velocity instead of [constant MIDI_MESSAGE_NOTE_OFF]. - For more information, see the note in [member velocity] and the MIDI message status byte list chart linked above. + Represents the type of MIDI message (see the [enum MIDIMessage] enum). + For more information, see the [url=https://www.midi.org/specifications-old/item/table-2-expanded-messages-list-status-bytes]MIDI message status byte list chart[/url]. </member> <member name="pitch" type="int" setter="set_pitch" getter="get_pitch" default="0"> - The pitch index number of this MIDI signal. This value ranges from 0 to 127. On a piano, middle C is 60, and A440 is 69, see the "MIDI note" column of the piano key frequency chart on Wikipedia for more information. + The pitch index number of this MIDI message. This value ranges from [code]0[/code] to [code]127[/code]. + On a piano, the [b]middle C[/b] is [code]60[/code], followed by a [b]C-sharp[/b] ([code]61[/code]), then a [b]D[/b] ([code]62[/code]), and so on. Each octave is split in offsets of 12. See the "MIDI note number" column of the [url=https://en.wikipedia.org/wiki/Piano_key_frequencies]piano key frequency chart[/url] a full list. </member> <member name="pressure" type="int" setter="set_pressure" getter="get_pressure" default="0"> - The pressure of the MIDI signal. This value ranges from 0 to 127. For many devices, this value is always zero. + The strength of the key being pressed. This value ranges from [code]0[/code] to [code]127[/code]. + [b]Note:[/b] For many devices, this value is always [code]0[/code]. Other devices such as musical keyboards may simulate pressure by changing the [member velocity], instead. </member> <member name="velocity" type="int" setter="set_velocity" getter="get_velocity" default="0"> - The velocity of the MIDI signal. This value ranges from 0 to 127. For a piano, this corresponds to how quickly the key was pressed, and is rarely above about 110 in practice. - [b]Note:[/b] Some MIDI devices may send a [constant MIDI_MESSAGE_NOTE_ON] message with zero velocity and expect this to be treated the same as a [constant MIDI_MESSAGE_NOTE_OFF] message, but device implementations vary so Godot reports event data exactly as received. Depending on the hardware and the needs of the game/app, this MIDI quirk can be handled robustly with a couple lines of script (check for [constant MIDI_MESSAGE_NOTE_ON] with velocity zero). + The velocity of the MIDI message. This value ranges from [code]0[/code] to [code]127[/code]. For a musical keyboard, this corresponds to how quickly the key was pressed, and is rarely above [code]110[/code] in practice. + [b]Note:[/b] Some MIDI devices may send a [constant MIDI_MESSAGE_NOTE_ON] message with [code]0[/code] velocity and expect it to be treated the same as a [constant MIDI_MESSAGE_NOTE_OFF] message. If necessary, this can be handled with a few lines of code: + [codeblock] + func _input(event): + if event is InputEventMIDI: + if event.message == MIDI_MESSAGE_NOTE_ON and event.velocity > 0: + print("Note pressed!") + [/codeblock] </member> </members> </class> diff --git a/doc/classes/InputEventMouseButton.xml b/doc/classes/InputEventMouseButton.xml index 57137e4bef..9bcd1fc7bf 100644 --- a/doc/classes/InputEventMouseButton.xml +++ b/doc/classes/InputEventMouseButton.xml @@ -1,10 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="InputEventMouseButton" inherits="InputEventMouse" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="InputEventMouseButton" inherits="InputEventMouse" keywords="click, press" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Represents a mouse button being pressed or released. </brief_description> <description> Stores information about mouse click events. See [method Node._input]. + [b]Note:[/b] On Wear OS devices, rotary input is mapped to [constant MOUSE_BUTTON_WHEEL_UP] and [constant MOUSE_BUTTON_WHEEL_DOWN]. This can be changed to [constant MOUSE_BUTTON_WHEEL_LEFT] and [constant MOUSE_BUTTON_WHEEL_RIGHT] with the [member ProjectSettings.input_devices/pointing/android/rotary_input_scroll_axis] setting. </description> <tutorials> <link title="Using InputEvent">$DOCS_URL/tutorials/inputs/inputevent.html</link> diff --git a/doc/classes/InputEventMouseMotion.xml b/doc/classes/InputEventMouseMotion.xml index 33a50d9daf..e6ec674975 100644 --- a/doc/classes/InputEventMouseMotion.xml +++ b/doc/classes/InputEventMouseMotion.xml @@ -23,12 +23,21 @@ <member name="relative" type="Vector2" setter="set_relative" getter="get_relative" default="Vector2(0, 0)"> The mouse position relative to the previous position (position at the last frame). [b]Note:[/b] Since [InputEventMouseMotion] is only emitted when the mouse moves, the last event won't have a relative position of [code]Vector2(0, 0)[/code] when the user stops moving the mouse. + [b]Note:[/b] [member relative] is automatically scaled according to the content scale factor, which is defined by the project's stretch mode settings. This means mouse sensitivity will appear different depending on resolution when using [member relative] in a script that handles mouse aiming with the [constant Input.MOUSE_MODE_CAPTURED] mouse mode. To avoid this, use [member screen_relative] instead. + </member> + <member name="screen_relative" type="Vector2" setter="set_screen_relative" getter="get_screen_relative" default="Vector2(0, 0)"> + The unscaled mouse position relative to the previous position in the coordinate system of the screen (position at the last frame). + [b]Note:[/b] Since [InputEventMouseMotion] is only emitted when the mouse moves, the last event won't have a relative position of [code]Vector2(0, 0)[/code] when the user stops moving the mouse. This coordinate is [i]not[/i] scaled according to the content scale factor or calls to [method InputEvent.xformed_by]. This should be preferred over [member relative] for mouse aiming when using the [constant Input.MOUSE_MODE_CAPTURED] mouse mode, regardless of the project's stretch mode. + </member> + <member name="screen_velocity" type="Vector2" setter="set_screen_velocity" getter="get_screen_velocity" default="Vector2(0, 0)"> + The unscaled mouse velocity in pixels per second in screen coordinates. This velocity is [i]not[/i] scaled according to the content scale factor or calls to [method InputEvent.xformed_by]. This should be preferred over [member velocity] for mouse aiming when using the [constant Input.MOUSE_MODE_CAPTURED] mouse mode, regardless of the project's stretch mode. </member> <member name="tilt" type="Vector2" setter="set_tilt" getter="get_tilt" default="Vector2(0, 0)"> Represents the angles of tilt of the pen. Positive X-coordinate value indicates a tilt to the right. Positive Y-coordinate value indicates a tilt toward the user. Ranges from [code]-1.0[/code] to [code]1.0[/code] for both axes. </member> <member name="velocity" type="Vector2" setter="set_velocity" getter="get_velocity" default="Vector2(0, 0)"> The mouse velocity in pixels per second. + [b]Note:[/b] [member velocity] is automatically scaled according to the content scale factor, which is defined by the project's stretch mode settings. This means mouse sensitivity will appear different depending on resolution when using [member velocity] in a script that handles mouse aiming with the [constant Input.MOUSE_MODE_CAPTURED] mouse mode. To avoid this, use [member screen_velocity] instead. </member> </members> </class> diff --git a/doc/classes/InputEventScreenDrag.xml b/doc/classes/InputEventScreenDrag.xml index 07c0a87180..e77040204c 100644 --- a/doc/classes/InputEventScreenDrag.xml +++ b/doc/classes/InputEventScreenDrag.xml @@ -17,19 +17,27 @@ Returns [code]true[/code] when using the eraser end of a stylus pen. </member> <member name="position" type="Vector2" setter="set_position" getter="get_position" default="Vector2(0, 0)"> - The drag position. + The drag position in the viewport the node is in, using the coordinate system of this viewport. </member> <member name="pressure" type="float" setter="set_pressure" getter="get_pressure" default="0.0"> Represents the pressure the user puts on the pen. Ranges from [code]0.0[/code] to [code]1.0[/code]. </member> <member name="relative" type="Vector2" setter="set_relative" getter="get_relative" default="Vector2(0, 0)"> The drag position relative to the previous position (position at the last frame). + [b]Note:[/b] [member relative] is automatically scaled according to the content scale factor, which is defined by the project's stretch mode settings. This means touch sensitivity will appear different depending on resolution when using [member relative] in a script that handles touch aiming. To avoid this, use [member screen_relative] instead. + </member> + <member name="screen_relative" type="Vector2" setter="set_screen_relative" getter="get_screen_relative" default="Vector2(0, 0)"> + The unscaled drag position relative to the previous position in screen coordinates (position at the last frame). This position is [i]not[/i] scaled according to the content scale factor or calls to [method InputEvent.xformed_by]. This should be preferred over [member relative] for touch aiming regardless of the project's stretch mode. + </member> + <member name="screen_velocity" type="Vector2" setter="set_screen_velocity" getter="get_screen_velocity" default="Vector2(0, 0)"> + The unscaled drag velocity in pixels per second in screen coordinates. This velocity is [i]not[/i] scaled according to the content scale factor or calls to [method InputEvent.xformed_by]. This should be preferred over [member velocity] for touch aiming regardless of the project's stretch mode. </member> <member name="tilt" type="Vector2" setter="set_tilt" getter="get_tilt" default="Vector2(0, 0)"> Represents the angles of tilt of the pen. Positive X-coordinate value indicates a tilt to the right. Positive Y-coordinate value indicates a tilt toward the user. Ranges from [code]-1.0[/code] to [code]1.0[/code] for both axes. </member> <member name="velocity" type="Vector2" setter="set_velocity" getter="get_velocity" default="Vector2(0, 0)"> The drag velocity. + [b]Note:[/b] [member velocity] is automatically scaled according to the content scale factor, which is defined by the project's stretch mode settings. This means touch sensitivity will appear different depending on resolution when using [member velocity] in a script that handles touch aiming. To avoid this, use [member screen_velocity] instead. </member> </members> </class> diff --git a/doc/classes/InputEventScreenTouch.xml b/doc/classes/InputEventScreenTouch.xml index 9ed6fc191c..a42b122e3b 100644 --- a/doc/classes/InputEventScreenTouch.xml +++ b/doc/classes/InputEventScreenTouch.xml @@ -20,7 +20,7 @@ The touch index in the case of a multi-touch event. One index = one finger. </member> <member name="position" type="Vector2" setter="set_position" getter="get_position" default="Vector2(0, 0)"> - The touch position, in screen (global) coordinates. + The touch position in the viewport the node is in, using the coordinate system of this viewport. </member> <member name="pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false"> If [code]true[/code], the touch's state is pressed. If [code]false[/code], the touch's state is released. diff --git a/doc/classes/ItemList.xml b/doc/classes/ItemList.xml index 593f41bc70..a1e5d9cbd9 100644 --- a/doc/classes/ItemList.xml +++ b/doc/classes/ItemList.xml @@ -461,7 +461,7 @@ <theme_item name="font_hovered_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)"> Text [Color] used when the item is hovered and not selected yet. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the item. </theme_item> <theme_item name="font_selected_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> @@ -483,7 +483,7 @@ The size of the item text outline. [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. </theme_item> - <theme_item name="v_separation" data_type="constant" type="int" default="2"> + <theme_item name="v_separation" data_type="constant" type="int" default="4"> The vertical spacing between items. </theme_item> <theme_item name="font" data_type="font" type="Font"> diff --git a/doc/classes/Label.xml b/doc/classes/Label.xml index f13f1bdcf4..f39f5616f0 100644 --- a/doc/classes/Label.xml +++ b/doc/classes/Label.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="Label" inherits="Control" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="Label" inherits="Control" keywords="text" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A control for displaying plain text. </brief_description> @@ -10,6 +10,13 @@ <link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/515</link> </tutorials> <methods> + <method name="get_character_bounds" qualifiers="const"> + <return type="Rect2" /> + <param index="0" name="pos" type="int" /> + <description> + Returns the bounding rectangle of the character at position [param pos]. If the character is a non-visual character or [param pos] is outside the valid range, an empty [Rect2] is returned. If the character is a part of a composite grapheme, the bounding rectangle of the whole grapheme is returned. + </description> + </method> <method name="get_line_count" qualifiers="const"> <return type="int" /> <description> @@ -45,6 +52,9 @@ <member name="clip_text" type="bool" setter="set_clip_text" getter="is_clipping_text" default="false"> If [code]true[/code], the Label only shows the text that fits inside its bounding rectangle and will clip text horizontally. </member> + <member name="ellipsis_char" type="String" setter="set_ellipsis_char" getter="get_ellipsis_char" default=""…""> + Ellipsis character used for text clipping. + </member> <member name="horizontal_alignment" type="int" setter="set_horizontal_alignment" getter="get_horizontal_alignment" enum="HorizontalAlignment" default="0"> Controls the text's horizontal alignment. Supports left, center, right, and fill, or justify. Set it to one of the [enum HorizontalAlignment] constants. </member> @@ -105,7 +115,7 @@ <theme_item name="font_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> Default text [Color] of the [Label]. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The color of text outline. </theme_item> <theme_item name="font_shadow_color" data_type="color" type="Color" default="Color(0, 0, 0, 0)"> @@ -117,6 +127,7 @@ <theme_item name="outline_size" data_type="constant" type="int" default="0"> Text outline size. [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. + [b]Note:[/b] Using a value that is larger than half the font size is not recommended, as the font outline may fail to be fully closed in this case. </theme_item> <theme_item name="shadow_offset_x" data_type="constant" type="int" default="1"> The horizontal offset of the text's shadow. diff --git a/doc/classes/Label3D.xml b/doc/classes/Label3D.xml index 977fb00402..4c70897452 100644 --- a/doc/classes/Label3D.xml +++ b/doc/classes/Label3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="Label3D" inherits="GeometryInstance3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="Label3D" inherits="GeometryInstance3D" keywords="text" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A node for displaying plain text in 3D space. </brief_description> @@ -81,7 +81,7 @@ <member name="line_spacing" type="float" setter="set_line_spacing" getter="get_line_spacing" default="0.0"> Vertical space between lines in multiline [Label3D]. </member> - <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)"> + <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)" keywords="color, colour"> Text [Color] of the [Label3D]. </member> <member name="no_depth_test" type="bool" setter="set_draw_flag" getter="get_draw_flag" default="false"> diff --git a/doc/classes/Light2D.xml b/doc/classes/Light2D.xml index 9e0cf664de..a1c1a57ae4 100644 --- a/doc/classes/Light2D.xml +++ b/doc/classes/Light2D.xml @@ -28,7 +28,7 @@ <member name="blend_mode" type="int" setter="set_blend_mode" getter="get_blend_mode" enum="Light2D.BlendMode" default="0"> The Light2D's blend mode. See [enum BlendMode] constants for values. </member> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour"> The Light2D's [Color]. </member> <member name="editor_only" type="bool" setter="set_editor_only" getter="is_editor_only" default="false"> diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml index d0bc7926ca..bffa20bf23 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -35,31 +35,31 @@ </method> </methods> <members> - <member name="distance_fade_begin" type="float" setter="set_distance_fade_begin" getter="get_distance_fade_begin" default="40.0"> + <member name="distance_fade_begin" type="float" setter="set_distance_fade_begin" getter="get_distance_fade_begin" default="40.0" keywords="lod_begin"> The distance from the camera at which the light begins to fade away (in 3D units). [b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D]. </member> - <member name="distance_fade_enabled" type="bool" setter="set_enable_distance_fade" getter="is_distance_fade_enabled" default="false"> + <member name="distance_fade_enabled" type="bool" setter="set_enable_distance_fade" getter="is_distance_fade_enabled" default="false" keywords="lod_enabled"> If [code]true[/code], the light will smoothly fade away when far from the active [Camera3D] starting at [member distance_fade_begin]. This acts as a form of level of detail (LOD). The light will fade out over [member distance_fade_begin] + [member distance_fade_length], after which it will be culled and not sent to the shader at all. Use this to reduce the number of active lights in a scene and thus improve performance. [b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D]. </member> - <member name="distance_fade_length" type="float" setter="set_distance_fade_length" getter="get_distance_fade_length" default="10.0"> + <member name="distance_fade_length" type="float" setter="set_distance_fade_length" getter="get_distance_fade_length" default="10.0" keywords="lod_length"> Distance over which the light and its shadow fades. The light's energy and shadow's opacity is progressively reduced over this distance and is completely invisible at the end. [b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D]. </member> - <member name="distance_fade_shadow" type="float" setter="set_distance_fade_shadow" getter="get_distance_fade_shadow" default="50.0"> + <member name="distance_fade_shadow" type="float" setter="set_distance_fade_shadow" getter="get_distance_fade_shadow" default="50.0" keywords="lod_shadow"> The distance from the camera at which the light's shadow cuts off (in 3D units). Set this to a value lower than [member distance_fade_begin] + [member distance_fade_length] to further improve performance, as shadow rendering is often more expensive than light rendering itself. [b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D], and only when [member shadow_enabled] is [code]true[/code]. </member> <member name="editor_only" type="bool" setter="set_editor_only" getter="is_editor_only" default="false"> If [code]true[/code], the light only appears in the editor and will not be visible at runtime. If [code]true[/code], the light will never be baked in [LightmapGI] regardless of its [member light_bake_mode]. </member> - <member name="light_angular_distance" type="float" setter="set_param" getter="get_param" default="0.0"> + <member name="light_angular_distance" type="float" setter="set_param" getter="get_param" default="0.0" keywords="pcss"> The light's angular size in degrees. Increasing this will make shadows softer at greater distances (also called percentage-closer soft shadows, or PCSS). Only available for [DirectionalLight3D]s. For reference, the Sun from the Earth is approximately [code]0.5[/code]. Increasing this value above [code]0.0[/code] for lights with shadows enabled will have a noticeable performance cost due to PCSS. [b]Note:[/b] [member light_angular_distance] is not affected by [member Node3D.scale] (the light's scale or its parent's scale). [b]Note:[/b] PCSS for directional lights is only supported in the Forward+ rendering method, not Mobile or Compatibility. </member> - <member name="light_bake_mode" type="int" setter="set_bake_mode" getter="get_bake_mode" enum="Light3D.BakeMode" default="2"> + <member name="light_bake_mode" type="int" setter="set_bake_mode" getter="get_bake_mode" enum="Light3D.BakeMode" default="2" keywords="global_illumination_mode, gi_mode"> The light's bake mode. This will affect the global illumination techniques that have an effect on the light's rendering. See [enum BakeMode]. [b]Note:[/b] Meshes' global illumination mode will also affect the global illumination rendering. See [member GeometryInstance3D.gi_mode]. </member> @@ -88,12 +88,12 @@ <member name="light_negative" type="bool" setter="set_negative" getter="is_negative" default="false"> If [code]true[/code], the light's effect is reversed, darkening areas and casting bright shadows. </member> - <member name="light_projector" type="Texture2D" setter="set_projector" getter="get_projector"> + <member name="light_projector" type="Texture2D" setter="set_projector" getter="get_projector" keywords="cookie, gobo"> [Texture2D] projected by light. [member shadow_enabled] must be on for the projector to work. Light projectors make the light appear as if it is shining through a colored but transparent object, almost like light shining through stained-glass. [b]Note:[/b] Unlike [BaseMaterial3D] whose filter mode can be adjusted on a per-material basis, the filter mode for light projector textures is set globally with [member ProjectSettings.rendering/textures/light_projectors/filter]. [b]Note:[/b] Light projector textures are only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> - <member name="light_size" type="float" setter="set_param" getter="get_param" default="0.0"> + <member name="light_size" type="float" setter="set_param" getter="get_param" default="0.0" keywords="pcss"> The size of the light in Godot units. Only available for [OmniLight3D]s and [SpotLight3D]s. Increasing this value will make the light fade out slower and shadows appear blurrier (also called percentage-closer soft shadows, or PCSS). This can be used to simulate area lights to an extent. Increasing this value above [code]0.0[/code] for lights with shadows enabled will have a noticeable performance cost due to PCSS. [b]Note:[/b] [member light_size] is not affected by [member Node3D.scale] (the light's scale or its parent's scale). [b]Note:[/b] PCSS for positional lights is only supported in the Forward+ and Mobile rendering methods, not Compatibility. diff --git a/doc/classes/LightmapGI.xml b/doc/classes/LightmapGI.xml index ec75d85898..13d48d8650 100644 --- a/doc/classes/LightmapGI.xml +++ b/doc/classes/LightmapGI.xml @@ -9,7 +9,7 @@ [b]Performance:[/b] [LightmapGI] provides the best possible run-time performance for global illumination. It is suitable for low-end hardware including integrated graphics and mobile devices. [b]Note:[/b] Due to how lightmaps work, most properties only have a visible effect once lightmaps are baked again. [b]Note:[/b] Lightmap baking on [CSGShape3D]s and [PrimitiveMesh]es is not supported, as these cannot store UV2 data required for baking. - [b]Note:[/b] If no custom lightmappers are installed, [LightmapGI] can only be baked when using the Vulkan backend (Forward+ or Mobile), not OpenGL. + [b]Note:[/b] If no custom lightmappers are installed, [LightmapGI] can only be baked from devices that support the Forward+ or Mobile rendering backends. </description> <tutorials> <link title="Using Lightmap global illumination">$DOCS_URL/tutorials/3d/global_illumination/using_lightmap_gi.html</link> @@ -65,6 +65,9 @@ The quality preset to use when baking lightmaps. This affects bake times, but output file sizes remain mostly identical across quality levels. To further speed up bake times, decrease [member bounces], disable [member use_denoiser] and increase the lightmap texel size on 3D scenes in the Import doc. </member> + <member name="texel_scale" type="float" setter="set_texel_scale" getter="get_texel_scale" default="1.0"> + Scales the lightmap texel density of all meshes for the current bake. This is a multiplier that builds upon the existing lightmap texel size defined in each imported 3D scene, along with the per-mesh density multiplier (which is designed to be used when the same mesh is used at different scales). Lower values will result in faster bake times. + </member> <member name="use_denoiser" type="bool" setter="set_use_denoiser" getter="is_using_denoiser" default="true"> If [code]true[/code], uses a GPU-based denoising algorithm on the generated lightmap. This eliminates most noise within the generated lightmap at the cost of longer bake times. File sizes are generally not impacted significantly by the use of a denoiser, although lossless compression may do a better job at compressing a denoised image. </member> diff --git a/doc/classes/LightmapGIData.xml b/doc/classes/LightmapGIData.xml index db6c9e70ca..76824f84a0 100644 --- a/doc/classes/LightmapGIData.xml +++ b/doc/classes/LightmapGIData.xml @@ -54,9 +54,8 @@ </method> </methods> <members> - <member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture" is_deprecated="true"> + <member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture" deprecated="The lightmap atlas can now contain multiple textures. See [member lightmap_textures]."> The lightmap atlas texture generated by the lightmapper. - [i]Deprecated.[/i] The lightmap atlas can now have multiple textures. See [member lightmap_textures]. </member> <member name="lightmap_textures" type="TextureLayered[]" setter="set_lightmap_textures" getter="get_lightmap_textures" default="[]"> The lightmap atlas textures generated by the lightmapper. diff --git a/doc/classes/LineEdit.xml b/doc/classes/LineEdit.xml index e706e3d6e0..77fff22157 100644 --- a/doc/classes/LineEdit.xml +++ b/doc/classes/LineEdit.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="LineEdit" inherits="Control" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="LineEdit" inherits="Control" keywords="text, input" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> An input field for single-line text. </brief_description> @@ -216,7 +216,7 @@ <member name="draw_control_chars" type="bool" setter="set_draw_control_chars" getter="get_draw_control_chars" default="false"> If [code]true[/code], control characters are displayed. </member> - <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true"> + <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true" keywords="readonly, disabled, enabled"> If [code]false[/code], existing text cannot be modified and new text cannot be added. </member> <member name="expand_to_text_length" type="bool" setter="set_expand_to_text_length_enabled" getter="is_expand_to_text_length_enabled" default="false"> @@ -454,7 +454,7 @@ <theme_item name="font_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)"> Default font color. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the [LineEdit]. </theme_item> <theme_item name="font_placeholder_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 0.6)"> @@ -494,7 +494,7 @@ <theme_item name="normal" data_type="style" type="StyleBox"> Default background for the [LineEdit]. </theme_item> - <theme_item name="read_only" data_type="style" type="StyleBox"> + <theme_item name="read_only" data_type="style" type="StyleBox" keywords="enabled, disabled, editable"> Background used when [LineEdit] is in read-only mode ([member editable] is set to [code]false[/code]). </theme_item> </theme_items> diff --git a/doc/classes/LinkButton.xml b/doc/classes/LinkButton.xml index aa81b6fde0..bcdffcd1ee 100644 --- a/doc/classes/LinkButton.xml +++ b/doc/classes/LinkButton.xml @@ -74,7 +74,7 @@ <theme_item name="font_hover_pressed_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> Text [Color] used when the [LinkButton] is being hovered and pressed. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the [LinkButton]. </theme_item> <theme_item name="font_pressed_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> diff --git a/doc/classes/MainLoop.xml b/doc/classes/MainLoop.xml index 4c6c9d3524..17cc0d78d3 100644 --- a/doc/classes/MainLoop.xml +++ b/doc/classes/MainLoop.xml @@ -5,7 +5,7 @@ </brief_description> <description> [MainLoop] is the abstract base class for a Godot project's game loop. It is inherited by [SceneTree], which is the default game loop implementation used in Godot projects, though it is also possible to write and use one's own [MainLoop] subclass instead of the scene tree. - Upon the application start, a [MainLoop] implementation must be provided to the OS; otherwise, the application will exit. This happens automatically (and a [SceneTree] is created) unless a [MainLoop] [Script] is provided from the command line (with e.g. [code]godot -s my_loop.gd[/code] or the "Main Loop Type" project setting is overwritten. + Upon the application start, a [MainLoop] implementation must be provided to the OS; otherwise, the application will exit. This happens automatically (and a [SceneTree] is created) unless a [MainLoop] [Script] is provided from the command line (with e.g. [code]godot -s my_loop.gd[/code]) or the "Main Loop Type" project setting is overwritten. Here is an example script implementing a simple [MainLoop]: [codeblocks] [gdscript] @@ -30,6 +30,7 @@ [csharp] using Godot; + [GlobalClass] public partial class CustomMainLoop : MainLoop { private double _timeElapsed = 0; @@ -119,19 +120,20 @@ </constant> <constant name="NOTIFICATION_APPLICATION_RESUMED" value="2014"> Notification received from the OS when the application is resumed. - Specific to the Android platform. + Specific to the Android and iOS platforms. </constant> <constant name="NOTIFICATION_APPLICATION_PAUSED" value="2015"> Notification received from the OS when the application is paused. - Specific to the Android platform. + Specific to the Android and iOS platforms. + [b]Note:[/b] On iOS, you only have approximately 5 seconds to finish a task started by this signal. If you go over this allotment, iOS will kill the app instead of pausing it. </constant> <constant name="NOTIFICATION_APPLICATION_FOCUS_IN" value="2016"> Notification received from the OS when the application is focused, i.e. when changing the focus from the OS desktop or a thirdparty application to any open window of the Godot instance. - Implemented on desktop platforms. + Implemented on desktop and mobile platforms. </constant> <constant name="NOTIFICATION_APPLICATION_FOCUS_OUT" value="2017"> Notification received from the OS when the application is defocused, i.e. when changing the focus from any open window of the Godot instance to the OS desktop or a thirdparty application. - Implemented on desktop platforms. + Implemented on desktop and mobile platforms. </constant> <constant name="NOTIFICATION_TEXT_SERVER_CHANGED" value="2018"> Notification received when text server is changed. diff --git a/doc/classes/MarginContainer.xml b/doc/classes/MarginContainer.xml index b83ee7ba00..e3dd64648f 100644 --- a/doc/classes/MarginContainer.xml +++ b/doc/classes/MarginContainer.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MarginContainer" inherits="Container" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MarginContainer" inherits="Container" keywords="padding" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A container that keeps a margin around its child controls. </brief_description> diff --git a/doc/classes/MenuBar.xml b/doc/classes/MenuBar.xml index 07f64d0572..9e4287331c 100644 --- a/doc/classes/MenuBar.xml +++ b/doc/classes/MenuBar.xml @@ -132,7 +132,7 @@ <theme_item name="font_hover_pressed_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> Text [Color] used when the menu item is being hovered and pressed. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the menu item. </theme_item> <theme_item name="font_pressed_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> @@ -151,7 +151,7 @@ <theme_item name="font_size" data_type="font_size" type="int"> Font size of the menu item's text. </theme_item> - <theme_item name="disabled" data_type="style" type="StyleBox"> + <theme_item name="disabled" data_type="style" type="StyleBox" keywords="enabled"> [StyleBox] used when the menu item is disabled. </theme_item> <theme_item name="disabled_mirrored" data_type="style" type="StyleBox"> diff --git a/doc/classes/Mesh.xml b/doc/classes/Mesh.xml index 2b2dc63a33..3f8ed91ad7 100644 --- a/doc/classes/Mesh.xml +++ b/doc/classes/Mesh.xml @@ -237,16 +237,16 @@ [PackedVector2Array] for second UV coordinates. </constant> <constant name="ARRAY_CUSTOM0" value="6" enum="ArrayType"> - Contains custom color channel 0. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM0_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RG_HALF] or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. + Contains custom color channel 0. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM0_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_SNORM], [constant ARRAY_CUSTOM_RG_HALF], or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. </constant> <constant name="ARRAY_CUSTOM1" value="7" enum="ArrayType"> - Contains custom color channel 1. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM1_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RG_HALF] or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. + Contains custom color channel 1. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM1_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_SNORM], [constant ARRAY_CUSTOM_RG_HALF], or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. </constant> <constant name="ARRAY_CUSTOM2" value="8" enum="ArrayType"> - Contains custom color channel 2. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM2_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RG_HALF] or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. + Contains custom color channel 2. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM2_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_SNORM], [constant ARRAY_CUSTOM_RG_HALF], or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. </constant> <constant name="ARRAY_CUSTOM3" value="9" enum="ArrayType"> - Contains custom color channel 3. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM3_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RG_HALF] or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. + Contains custom color channel 3. [PackedByteArray] if [code](format >> Mesh.ARRAY_FORMAT_CUSTOM3_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK[/code] is [constant ARRAY_CUSTOM_RGBA8_UNORM], [constant ARRAY_CUSTOM_RGBA8_SNORM], [constant ARRAY_CUSTOM_RG_HALF], or [constant ARRAY_CUSTOM_RGBA_HALF]. [PackedFloat32Array] otherwise. </constant> <constant name="ARRAY_BONES" value="10" enum="ArrayType"> [PackedFloat32Array] or [PackedInt32Array] of bone indices. Contains either 4 or 8 numbers per vertex depending on the presence of the [constant ARRAY_FLAG_USE_8_BONE_WEIGHTS] flag. diff --git a/doc/classes/MeshConvexDecompositionSettings.xml b/doc/classes/MeshConvexDecompositionSettings.xml index 161fd1c114..38f1ff3f9b 100644 --- a/doc/classes/MeshConvexDecompositionSettings.xml +++ b/doc/classes/MeshConvexDecompositionSettings.xml @@ -10,7 +10,7 @@ </tutorials> <members> <member name="convex_hull_approximation" type="bool" setter="set_convex_hull_approximation" getter="get_convex_hull_approximation" default="true"> - If enabled uses approximation for computing convex hulls. + If [code]true[/code], uses approximation for computing convex hulls. </member> <member name="convex_hull_downsampling" type="int" setter="set_convex_hull_downsampling" getter="get_convex_hull_downsampling" default="4"> Controls the precision of the convex-hull generation process during the clipping plane selection stage. Ranges from [code]1[/code] to [code]16[/code]. @@ -31,13 +31,13 @@ Mode for the approximate convex decomposition. </member> <member name="normalize_mesh" type="bool" setter="set_normalize_mesh" getter="get_normalize_mesh" default="false"> - If enabled normalizes the mesh before applying the convex decomposition. + If [code]true[/code], normalizes the mesh before applying the convex decomposition. </member> <member name="plane_downsampling" type="int" setter="set_plane_downsampling" getter="get_plane_downsampling" default="4"> Controls the granularity of the search for the "best" clipping plane. Ranges from [code]1[/code] to [code]16[/code]. </member> <member name="project_hull_vertices" type="bool" setter="set_project_hull_vertices" getter="get_project_hull_vertices" default="true"> - If enabled projects output convex hull vertices onto original source mesh to increase floating point accuracy of the results. + If [code]true[/code], projects output convex hull vertices onto the original source mesh to increase floating-point accuracy of the results. </member> <member name="resolution" type="int" setter="set_resolution" getter="get_resolution" default="10000"> Maximum number of voxels generated during the voxelization stage. diff --git a/doc/classes/MeshDataTool.xml b/doc/classes/MeshDataTool.xml index 1b8ae8cc59..0b9890b2ec 100644 --- a/doc/classes/MeshDataTool.xml +++ b/doc/classes/MeshDataTool.xml @@ -158,8 +158,7 @@ <method name="get_format" qualifiers="const"> <return type="int" /> <description> - Returns the [Mesh]'s format. Format is an integer made up of [Mesh] format flags combined together. For example, a mesh containing both vertices and normals would return a format of [code]3[/code] because [constant Mesh.ARRAY_FORMAT_VERTEX] is [code]1[/code] and [constant Mesh.ARRAY_FORMAT_NORMAL] is [code]2[/code]. - See [enum Mesh.ArrayFormat] for a list of format flags. + Returns the [Mesh]'s format as a combination of the [enum Mesh.ArrayFormat] flags. For example, a mesh containing both vertices and normals would return a format of [code]3[/code] because [constant Mesh.ARRAY_FORMAT_VERTEX] is [code]1[/code] and [constant Mesh.ARRAY_FORMAT_NORMAL] is [code]2[/code]. </description> </method> <method name="get_material" qualifiers="const"> diff --git a/doc/classes/MissingNode.xml b/doc/classes/MissingNode.xml index 6e5f839778..9171c8321f 100644 --- a/doc/classes/MissingNode.xml +++ b/doc/classes/MissingNode.xml @@ -4,15 +4,20 @@ An internal editor class intended for keeping the data of unrecognized nodes. </brief_description> <description> - This is an internal editor class intended for keeping data of nodes of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in the scene. Ignore it if you don't know what it is. + This is an internal editor class intended for keeping data of nodes of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in a scene. + [b]Warning:[/b] Ignore missing nodes unless you know what you are doing. Existing properties on a missing node can be freely modified in code, regardless of the type they are intended to be. </description> <tutorials> </tutorials> <members> <member name="original_class" type="String" setter="set_original_class" getter="get_original_class"> - Returns the name of the type this node was originally. + The name of the class this node was supposed to be (see [method Object.get_class]). + </member> + <member name="original_scene" type="String" setter="set_original_scene" getter="get_original_scene"> + Returns the path of the scene this node was instance of originally. </member> <member name="recording_properties" type="bool" setter="set_recording_properties" getter="is_recording_properties"> + If [code]true[/code], allows new properties to be set along with existing ones. If [code]false[/code], only existing properties' values can be set, and new properties cannot be added. </member> </members> </class> diff --git a/doc/classes/MissingResource.xml b/doc/classes/MissingResource.xml index 84a12290b3..442b0abd5e 100644 --- a/doc/classes/MissingResource.xml +++ b/doc/classes/MissingResource.xml @@ -4,15 +4,17 @@ An internal editor class intended for keeping the data of unrecognized resources. </brief_description> <description> - This is an internal editor class intended for keeping data of resources of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in the scene. Ignore it if you don't know what it is. + This is an internal editor class intended for keeping data of resources of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in a scene. + [b]Warning:[/b] Ignore missing resources unless you know what you are doing. Existing properties on a missing resource can be freely modified in code, regardless of the type they are intended to be. </description> <tutorials> </tutorials> <members> <member name="original_class" type="String" setter="set_original_class" getter="get_original_class"> - Returns the name of the class this resource was originally. + The name of the class this resource was supposed to be (see [method Object.get_class]). </member> <member name="recording_properties" type="bool" setter="set_recording_properties" getter="is_recording_properties"> + If set to [code]true[/code], allows new properties to be added on top of the existing ones with [method Object.set]. </member> </members> </class> diff --git a/doc/classes/MultiMesh.xml b/doc/classes/MultiMesh.xml index f83dadfb15..406aacc75c 100644 --- a/doc/classes/MultiMesh.xml +++ b/doc/classes/MultiMesh.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MultiMesh" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MultiMesh" inherits="Resource" keywords="batch" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Provides high-performance drawing of a mesh multiple times using GPU instancing. </brief_description> @@ -65,7 +65,7 @@ <param index="0" name="instance" type="int" /> <param index="1" name="custom_data" type="Color" /> <description> - Sets custom data for a specific instance. Although [Color] is used, it is just a container for 4 floating point numbers. + Sets custom data for a specific instance. [param custom_data] is a [Color] type only to contain 4 floating-point numbers. For the custom data to be used, ensure that [member use_custom_data] is [code]true[/code]. This custom instance data has to be manually accessed in your custom shader using [code]INSTANCE_CUSTOM[/code]. </description> @@ -90,11 +90,14 @@ <members> <member name="buffer" type="PackedFloat32Array" setter="set_buffer" getter="get_buffer" default="PackedFloat32Array()"> </member> - <member name="color_array" type="PackedColorArray" setter="_set_color_array" getter="_get_color_array" is_deprecated="true"> - See [method set_instance_color]. + <member name="color_array" type="PackedColorArray" setter="_set_color_array" getter="_get_color_array" deprecated="Accessing this property is very slow. Use [method set_instance_color] and [method get_instance_color] instead."> + Array containing each [Color] used by all instances of this mesh. </member> - <member name="custom_data_array" type="PackedColorArray" setter="_set_custom_data_array" getter="_get_custom_data_array" is_deprecated="true"> - See [method set_instance_custom_data]. + <member name="custom_aabb" type="AABB" setter="set_custom_aabb" getter="get_custom_aabb" default="AABB(0, 0, 0, 0, 0, 0)"> + Custom AABB for this MultiMesh resource. Setting this manually prevents costly runtime AABB recalculations. + </member> + <member name="custom_data_array" type="PackedColorArray" setter="_set_custom_data_array" getter="_get_custom_data_array" deprecated="Accessing this property is very slow. Use [method set_instance_custom_data] and [method get_instance_custom_data] instead."> + Array containing each custom data value used by all instances of this mesh, as a [PackedColorArray]. </member> <member name="instance_count" type="int" setter="set_instance_count" getter="get_instance_count" default="0"> Number of instances that will get drawn. This clears and (re)sizes the buffers. Setting data format or flags afterwards will have no effect. @@ -104,11 +107,11 @@ [Mesh] resource to be instanced. The looks of the individual instances can be modified using [method set_instance_color] and [method set_instance_custom_data]. </member> - <member name="transform_2d_array" type="PackedVector2Array" setter="_set_transform_2d_array" getter="_get_transform_2d_array" is_deprecated="true"> - See [method set_instance_transform_2d]. + <member name="transform_2d_array" type="PackedVector2Array" setter="_set_transform_2d_array" getter="_get_transform_2d_array" deprecated="Accessing this property is very slow. Use [method set_instance_transform_2d] and [method get_instance_transform_2d] instead."> + Array containing each [Transform2D] value used by all instances of this mesh, as a [PackedVector2Array]. Each transform is divided into 3 [Vector2] values corresponding to the transforms' [code]x[/code], [code]y[/code], and [code]origin[/code]. </member> - <member name="transform_array" type="PackedVector3Array" setter="_set_transform_array" getter="_get_transform_array" is_deprecated="true"> - See [method set_instance_transform]. + <member name="transform_array" type="PackedVector3Array" setter="_set_transform_array" getter="_get_transform_array" deprecated="Accessing this property is very slow. Use [method set_instance_transform] and [method get_instance_transform] instead."> + Array containing each [Transform3D] value used by all instances of this mesh, as a [PackedVector3Array]. Each transform is divided into 4 [Vector3] values corresponding to the transforms' [code]x[/code], [code]y[/code], [code]z[/code], and [code]origin[/code]. </member> <member name="transform_format" type="int" setter="set_transform_format" getter="get_transform_format" enum="MultiMesh.TransformFormat" default="0"> Format of transform used to transform mesh, either 2D or 3D. diff --git a/doc/classes/MultiMeshInstance2D.xml b/doc/classes/MultiMeshInstance2D.xml index dc38d920bc..0d8a0e136a 100644 --- a/doc/classes/MultiMeshInstance2D.xml +++ b/doc/classes/MultiMeshInstance2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MultiMeshInstance2D" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MultiMeshInstance2D" inherits="Node2D" keywords="batch" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Node that instances a [MultiMesh] in 2D. </brief_description> diff --git a/doc/classes/MultiMeshInstance3D.xml b/doc/classes/MultiMeshInstance3D.xml index 65abd174ed..5b6fd92d99 100644 --- a/doc/classes/MultiMeshInstance3D.xml +++ b/doc/classes/MultiMeshInstance3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MultiMeshInstance3D" inherits="GeometryInstance3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MultiMeshInstance3D" inherits="GeometryInstance3D" keywords="batch" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Node that instances a [MultiMesh]. </brief_description> diff --git a/doc/classes/MultiplayerAPI.xml b/doc/classes/MultiplayerAPI.xml index 95baf7c706..d5016867a7 100644 --- a/doc/classes/MultiplayerAPI.xml +++ b/doc/classes/MultiplayerAPI.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MultiplayerAPI" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MultiplayerAPI" inherits="RefCounted" keywords="network" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> High-level multiplayer API interface. </brief_description> @@ -34,7 +34,7 @@ <return type="int" /> <description> Returns the sender's peer ID for the RPC currently being executed. - [b]Note:[/b] If not inside an RPC this method will return 0. + [b]Note:[/b] This method returns [code]0[/code] when called outside of an RPC. As such, the original peer ID may be lost when code execution is delayed (such as with GDScript's [code]await[/code] keyword). </description> </method> <method name="get_unique_id"> diff --git a/doc/classes/MultiplayerAPIExtension.xml b/doc/classes/MultiplayerAPIExtension.xml index 7f6e7951b2..cc6d3b7fcf 100644 --- a/doc/classes/MultiplayerAPIExtension.xml +++ b/doc/classes/MultiplayerAPIExtension.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MultiplayerAPIExtension" inherits="MultiplayerAPI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MultiplayerAPIExtension" inherits="MultiplayerAPI" keywords="network" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Base class used for extending the [MultiplayerAPI]. </brief_description> diff --git a/doc/classes/MultiplayerPeer.xml b/doc/classes/MultiplayerPeer.xml index 350fffed32..04fd282457 100644 --- a/doc/classes/MultiplayerPeer.xml +++ b/doc/classes/MultiplayerPeer.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MultiplayerPeer" inherits="PacketPeer" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MultiplayerPeer" inherits="PacketPeer" keywords="network" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Abstract class for specialized [PacketPeer]s used by the [MultiplayerAPI]. </brief_description> @@ -48,7 +48,7 @@ <method name="get_packet_mode" qualifiers="const"> <return type="int" enum="MultiplayerPeer.TransferMode" /> <description> - Returns the [enum MultiplayerPeer.TransferMode] the remote peer used to send the next available packet. See [method PacketPeer.get_available_packet_count]. + Returns the transfer mode the remote peer used to send the next available packet. See [method PacketPeer.get_available_packet_count]. </description> </method> <method name="get_packet_peer" qualifiers="const"> diff --git a/doc/classes/MultiplayerPeerExtension.xml b/doc/classes/MultiplayerPeerExtension.xml index 9b2b5dbc94..b7d55f31b6 100644 --- a/doc/classes/MultiplayerPeerExtension.xml +++ b/doc/classes/MultiplayerPeerExtension.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="MultiplayerPeerExtension" inherits="MultiplayerPeer" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="MultiplayerPeerExtension" inherits="MultiplayerPeer" keywords="network" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Class that can be inherited to implement custom multiplayer API networking layers via GDExtension. </brief_description> @@ -58,7 +58,7 @@ <method name="_get_packet_mode" qualifiers="virtual const"> <return type="int" enum="MultiplayerPeer.TransferMode" /> <description> - Called to get the [enum MultiplayerPeer.TransferMode] the remote peer used to send the next available packet. See [method MultiplayerPeer.get_packet_mode]. + Called to get the transfer mode the remote peer used to send the next available packet. See [method MultiplayerPeer.get_packet_mode]. </description> </method> <method name="_get_packet_peer" qualifiers="virtual const"> diff --git a/doc/classes/NativeMenu.xml b/doc/classes/NativeMenu.xml new file mode 100644 index 0000000000..475874dee7 --- /dev/null +++ b/doc/classes/NativeMenu.xml @@ -0,0 +1,750 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="NativeMenu" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A server interface for OS native menus. + </brief_description> + <description> + [NativeMenu] handles low-level access to the OS native global menu bar and popup menus. + [b]Note:[/b] This is low-level API, consider using [MenuBar] with [member MenuBar.prefer_global_menu] set to [code]true[/code], and [PopupMenu] with [member PopupMenu.prefer_native_menu] set to [code]true[/code]. + To create a menu, use [method create_menu], add menu items using [code]add_*_item[/code] methods. To remove a menu, use [method free_menu]. + [codeblock] + var menu + + func _menu_callback(item_id): + if item_id == "ITEM_CUT": + cut() + elif item_id == "ITEM_COPY": + copy() + elif item_id == "ITEM_PASTE": + paste() + + func _enter_tree(): + # Create new menu and add items: + menu = NativeMenu.create_menu() + NativeMenu.add_item(menu, "Cut", _menu_callback, Callable(), "ITEM_CUT") + NativeMenu.add_item(menu, "Copy", _menu_callback, Callable(), "ITEM_COPY") + NativeMenu.add_separator(menu) + NativeMenu.add_item(menu, "Paste", _menu_callback, Callable(), "ITEM_PASTE") + + func _on_button_pressed(): + # Show popup menu at mouse position: + NativeMenu.popup(menu, DisplayServer.mouse_get_position()) + + func _exit_tree(): + # Remove menu when it's no longer needed: + NativeMenu.free_menu(menu) + [/codeblock] + </description> + <tutorials> + </tutorials> + <methods> + <method name="add_check_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="label" type="String" /> + <param index="2" name="callback" type="Callable" default="Callable()" /> + <param index="3" name="key_callback" type="Callable" default="Callable()" /> + <param index="4" name="tag" type="Variant" default="null" /> + <param index="5" name="accelerator" type="int" enum="Key" default="0" /> + <param index="6" name="index" type="int" default="-1" /> + <description> + Adds a new checkable item with text [param label] to the global menu [param rid]. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] On Windows, [param accelerator] and [param key_callback] are ignored. + </description> + </method> + <method name="add_icon_check_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="icon" type="Texture2D" /> + <param index="2" name="label" type="String" /> + <param index="3" name="callback" type="Callable" default="Callable()" /> + <param index="4" name="key_callback" type="Callable" default="Callable()" /> + <param index="5" name="tag" type="Variant" default="null" /> + <param index="6" name="accelerator" type="int" enum="Key" default="0" /> + <param index="7" name="index" type="int" default="-1" /> + <description> + Adds a new checkable item with text [param label] and icon [param icon] to the global menu [param rid]. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] On Windows, [param accelerator] and [param key_callback] are ignored. + </description> + </method> + <method name="add_icon_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="icon" type="Texture2D" /> + <param index="2" name="label" type="String" /> + <param index="3" name="callback" type="Callable" default="Callable()" /> + <param index="4" name="key_callback" type="Callable" default="Callable()" /> + <param index="5" name="tag" type="Variant" default="null" /> + <param index="6" name="accelerator" type="int" enum="Key" default="0" /> + <param index="7" name="index" type="int" default="-1" /> + <description> + Adds a new item with text [param label] and icon [param icon] to the global menu [param rid]. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] On Windows, [param accelerator] and [param key_callback] are ignored. + </description> + </method> + <method name="add_icon_radio_check_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="icon" type="Texture2D" /> + <param index="2" name="label" type="String" /> + <param index="3" name="callback" type="Callable" default="Callable()" /> + <param index="4" name="key_callback" type="Callable" default="Callable()" /> + <param index="5" name="tag" type="Variant" default="null" /> + <param index="6" name="accelerator" type="int" enum="Key" default="0" /> + <param index="7" name="index" type="int" default="-1" /> + <description> + Adds a new radio-checkable item with text [param label] and icon [param icon] to the global menu [param rid]. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method set_item_checked] for more info on how to control it. + [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] On Windows, [param accelerator] and [param key_callback] are ignored. + </description> + </method> + <method name="add_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="label" type="String" /> + <param index="2" name="callback" type="Callable" default="Callable()" /> + <param index="3" name="key_callback" type="Callable" default="Callable()" /> + <param index="4" name="tag" type="Variant" default="null" /> + <param index="5" name="accelerator" type="int" enum="Key" default="0" /> + <param index="6" name="index" type="int" default="-1" /> + <description> + Adds a new item with text [param label] to the global menu [param rid]. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] On Windows, [param accelerator] and [param key_callback] are ignored. + </description> + </method> + <method name="add_multistate_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="label" type="String" /> + <param index="2" name="max_states" type="int" /> + <param index="3" name="default_state" type="int" /> + <param index="4" name="callback" type="Callable" default="Callable()" /> + <param index="5" name="key_callback" type="Callable" default="Callable()" /> + <param index="6" name="tag" type="Variant" default="null" /> + <param index="7" name="accelerator" type="int" enum="Key" default="0" /> + <param index="8" name="index" type="int" default="-1" /> + <description> + Adds a new item with text [param label] to the global menu [param rid]. + Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. Each press or activate of the item will increase the state by one. The default value is defined by [param default_state]. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] By default, there's no indication of the current item state, it should be changed manually. + [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] On Windows, [param accelerator] and [param key_callback] are ignored. + </description> + </method> + <method name="add_radio_check_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="label" type="String" /> + <param index="2" name="callback" type="Callable" default="Callable()" /> + <param index="3" name="key_callback" type="Callable" default="Callable()" /> + <param index="4" name="tag" type="Variant" default="null" /> + <param index="5" name="accelerator" type="int" enum="Key" default="0" /> + <param index="6" name="index" type="int" default="-1" /> + <description> + Adds a new radio-checkable item with text [param label] to the global menu [param rid]. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method set_item_checked] for more info on how to control it. + [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] On Windows, [param accelerator] and [param key_callback] are ignored. + </description> + </method> + <method name="add_separator"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="index" type="int" default="-1" /> + <description> + Adds a separator between items to the global menu [param rid]. Separators also occupy an index. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="add_submenu_item"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="label" type="String" /> + <param index="2" name="submenu_rid" type="RID" /> + <param index="3" name="tag" type="Variant" default="null" /> + <param index="4" name="index" type="int" default="-1" /> + <description> + Adds an item that will act as a submenu of the global menu [param rid]. The [param submenu_rid] argument is the RID of the global menu that will be shown when the item is clicked. + Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="clear"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <description> + Removes all items from the global menu [param rid]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="create_menu"> + <return type="RID" /> + <description> + Creates a new global menu object. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="find_item_index_with_submenu" qualifiers="const"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="submenu_rid" type="RID" /> + <description> + Returns the index of the item with the submenu specified by [param submenu_rid]. Indices are automatically assigned to each item by the engine, and cannot be set manually. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="find_item_index_with_tag" qualifiers="const"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="tag" type="Variant" /> + <description> + Returns the index of the item with the specified [param tag]. Indices are automatically assigned to each item by the engine, and cannot be set manually. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="find_item_index_with_text" qualifiers="const"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="text" type="String" /> + <description> + Returns the index of the item with the specified [param text]. Indices are automatically assigned to each item by the engine, and cannot be set manually. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="free_menu"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <description> + Frees a global menu object created by this [NativeMenu]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_accelerator" qualifiers="const"> + <return type="int" enum="Key" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the accelerator of the item at index [param idx]. Accelerators are special combinations of keys that activate the item, no matter which control is focused. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_item_callback" qualifiers="const"> + <return type="Callable" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the callback of the item at index [param idx]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_count" qualifiers="const"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <description> + Returns number of items in the global menu [param rid]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_icon" qualifiers="const"> + <return type="Texture2D" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the icon of the item at index [param idx]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_indentation_level" qualifiers="const"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the horizontal offset of the item at the given [param idx]. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_item_key_callback" qualifiers="const"> + <return type="Callable" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the callback of the item accelerator at index [param idx]. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_item_max_states" qualifiers="const"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns number of states of a multistate item. See [method add_multistate_item] for details. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_state" qualifiers="const"> + <return type="int" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the state of a multistate item. See [method add_multistate_item] for details. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_submenu" qualifiers="const"> + <return type="RID" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the submenu ID of the item at index [param idx]. See [method add_submenu_item] for more info on how to add a submenu. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_tag" qualifiers="const"> + <return type="Variant" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the metadata of the specified item, which might be of any type. You can set it with [method set_item_tag], which provides a simple way of assigning context data to items. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_text" qualifiers="const"> + <return type="String" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the text of the item at index [param idx]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_item_tooltip" qualifiers="const"> + <return type="String" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns the tooltip associated with the specified index [param idx]. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_minimum_width" qualifiers="const"> + <return type="float" /> + <param index="0" name="rid" type="RID" /> + <description> + Returns global menu minimum width. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_popup_close_callback" qualifiers="const"> + <return type="Callable" /> + <param index="0" name="rid" type="RID" /> + <description> + Returns global menu close callback. + b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_popup_open_callback" qualifiers="const"> + <return type="Callable" /> + <param index="0" name="rid" type="RID" /> + <description> + Returns global menu open callback. + b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_size" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="rid" type="RID" /> + <description> + Returns global menu size. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="get_system_menu" qualifiers="const"> + <return type="RID" /> + <param index="0" name="menu_id" type="int" enum="NativeMenu.SystemMenus" /> + <description> + Returns RID of a special system menu. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="get_system_menu_name" qualifiers="const"> + <return type="String" /> + <param index="0" name="menu_id" type="int" enum="NativeMenu.SystemMenus" /> + <description> + Returns readable name of a special system menu. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="has_feature" qualifiers="const"> + <return type="bool" /> + <param index="0" name="feature" type="int" enum="NativeMenu.Feature" /> + <description> + Returns [code]true[/code] if the specified [param feature] is supported by the current [NativeMenu], [code]false[/code] otherwise. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="has_menu" qualifiers="const"> + <return type="bool" /> + <param index="0" name="rid" type="RID" /> + <description> + Returns [code]true[/code] if [param rid] is valid global menu. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="has_system_menu" qualifiers="const"> + <return type="bool" /> + <param index="0" name="menu_id" type="int" enum="NativeMenu.SystemMenus" /> + <description> + Returns [code]true[/code] if a special system menu is supported. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="is_item_checkable" qualifiers="const"> + <return type="bool" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns [code]true[/code] if the item at index [param idx] is checkable in some way, i.e. if it has a checkbox or radio button. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="is_item_checked" qualifiers="const"> + <return type="bool" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns [code]true[/code] if the item at index [param idx] is checked. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="is_item_disabled" qualifiers="const"> + <return type="bool" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns [code]true[/code] if the item at index [param idx] is disabled. When it is disabled it can't be selected, or its action invoked. + See [method set_item_disabled] for more info on how to disable an item. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="is_item_hidden" qualifiers="const"> + <return type="bool" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns [code]true[/code] if the item at index [param idx] is hidden. + See [method set_item_hidden] for more info on how to hide an item. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="is_item_radio_checkable" qualifiers="const"> + <return type="bool" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Returns [code]true[/code] if the item at index [param idx] has radio button-style checkability. + [b]Note:[/b] This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="is_system_menu" qualifiers="const"> + <return type="bool" /> + <param index="0" name="rid" type="RID" /> + <description> + Return [code]true[/code] is global menu is a special system menu. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="popup"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="position" type="Vector2i" /> + <description> + Shows the global menu at [param position] in the screen coordinates. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="remove_item"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <description> + Removes the item at index [param idx] from the global menu [param rid]. + [b]Note:[/b] The indices of items after the removed item will be shifted by one. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_interface_direction"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="is_rtl" type="bool" /> + <description> + Sets the menu text layout direction from right-to-left if [param is_rtl] is [code]true[/code]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_accelerator"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="keycode" type="int" enum="Key" /> + <description> + Sets the accelerator of the item at index [param idx]. [param keycode] can be a single [enum Key], or a combination of [enum KeyModifierMask]s and [enum Key]s using bitwise OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_item_callback"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="callback" type="Callable" /> + <description> + Sets the callback of the item at index [param idx]. Callback is emitted when an item is pressed. + [b]Note:[/b] The [param callback] Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the [code]tag[/code] parameter when the menu item was created. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_checkable"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="checkable" type="bool" /> + <description> + Sets whether the item at index [param idx] has a checkbox. If [code]false[/code], sets the type of the item to plain text. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_checked"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="checked" type="bool" /> + <description> + Sets the checkstate status of the item at index [param idx]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_disabled"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="disabled" type="bool" /> + <description> + Enables/disables the item at index [param idx]. When it is disabled, it can't be selected and its action can't be invoked. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_hidden"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="hidden" type="bool" /> + <description> + Hides/shows the item at index [param idx]. When it is hidden, an item does not appear in a menu and its action cannot be invoked. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_item_hover_callbacks"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="callback" type="Callable" /> + <description> + Sets the callback of the item at index [param idx]. The callback is emitted when an item is hovered. + [b]Note:[/b] The [param callback] Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the [code]tag[/code] parameter when the menu item was created. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_item_icon"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="icon" type="Texture2D" /> + <description> + Replaces the [Texture2D] icon of the specified [param idx]. + [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] This method is not supported by macOS Dock menu items. + </description> + </method> + <method name="set_item_indentation_level"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="level" type="int" /> + <description> + Sets the horizontal offset of the item at the given [param idx]. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_item_key_callback"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="key_callback" type="Callable" /> + <description> + Sets the callback of the item at index [param idx]. Callback is emitted when its accelerator is activated. + [b]Note:[/b] The [param key_callback] Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the [code]tag[/code] parameter when the menu item was created. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_item_max_states"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="max_states" type="int" /> + <description> + Sets number of state of a multistate item. See [method add_multistate_item] for details. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_radio_checkable"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="checkable" type="bool" /> + <description> + Sets the type of the item at the specified index [param idx] to radio button. If [code]false[/code], sets the type of the item to plain text. + [b]Note:[/b] This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_state"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="state" type="int" /> + <description> + Sets the state of a multistate item. See [method add_multistate_item] for details. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_submenu"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="submenu_rid" type="RID" /> + <description> + Sets the submenu RID of the item at index [param idx]. The submenu is a global menu that would be shown when the item is clicked. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_tag"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="tag" type="Variant" /> + <description> + Sets the metadata of an item, which may be of any type. You can later get it with [method get_item_tag], which provides a simple way of assigning context data to items. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_text"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="text" type="String" /> + <description> + Sets the text of the item at index [param idx]. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> + <method name="set_item_tooltip"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="idx" type="int" /> + <param index="2" name="tooltip" type="String" /> + <description> + Sets the [String] tooltip of the item at the specified index [param idx]. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_minimum_width"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="width" type="float" /> + <description> + Sets the minimum width of the global menu. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_popup_close_callback"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="callback" type="Callable" /> + <description> + Registers callable to emit when the menu is about to show. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + <method name="set_popup_open_callback"> + <return type="void" /> + <param index="0" name="rid" type="RID" /> + <param index="1" name="callback" type="Callable" /> + <description> + Registers callable to emit when the menu is about to closed. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> + </methods> + <constants> + <constant name="FEATURE_GLOBAL_MENU" value="0" enum="Feature"> + [NativeMenu] supports native global main menu. + </constant> + <constant name="FEATURE_POPUP_MENU" value="1" enum="Feature"> + [NativeMenu] supports native popup menus. + </constant> + <constant name="FEATURE_OPEN_CLOSE_CALLBACK" value="2" enum="Feature"> + [NativeMenu] supports menu open and close callbacks. + </constant> + <constant name="FEATURE_HOVER_CALLBACK" value="3" enum="Feature"> + [NativeMenu] supports menu item hover callback. + </constant> + <constant name="FEATURE_KEY_CALLBACK" value="4" enum="Feature"> + [NativeMenu] supports menu item accelerator/key callback. + </constant> + <constant name="INVALID_MENU_ID" value="0" enum="SystemMenus"> + Invalid special system menu ID. + </constant> + <constant name="MAIN_MENU_ID" value="1" enum="SystemMenus"> + Global main menu ID. + </constant> + <constant name="APPLICATION_MENU_ID" value="2" enum="SystemMenus"> + Application (first menu after "Apple" menu on macOS) menu ID. + </constant> + <constant name="WINDOW_MENU_ID" value="3" enum="SystemMenus"> + "Window" menu ID (on macOS this menu includes standard window control items and a list of open windows). + </constant> + <constant name="HELP_MENU_ID" value="4" enum="SystemMenus"> + "Help" menu ID (on macOS this menu includes help search bar). + </constant> + <constant name="DOCK_MENU_ID" value="5" enum="SystemMenus"> + Dock icon right-click menu ID (on macOS this menu include standard application control items and a list of open windows). + </constant> + </constants> +</class> diff --git a/doc/classes/NavigationAgent2D.xml b/doc/classes/NavigationAgent2D.xml index 4df8d4143b..132ece53b0 100644 --- a/doc/classes/NavigationAgent2D.xml +++ b/doc/classes/NavigationAgent2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationAgent2D" inherits="Node" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationAgent2D" inherits="Node" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A 2D agent used to pathfind to a position while avoiding obstacles. </brief_description> @@ -84,8 +84,8 @@ <method name="is_navigation_finished"> <return type="bool" /> <description> - Returns [code]true[/code] if the end of the currently loaded navigation path has been reached. - [b]Note:[/b] While true prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. + Returns [code]true[/code] if the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. + [b]Note:[/b] While [code]true[/code] prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. </description> </method> <method name="is_target_reachable"> @@ -97,7 +97,7 @@ <method name="is_target_reached" qualifiers="const"> <return type="bool" /> <description> - Returns true if [member target_position] is reached. It may not always be possible to reach the target position. It should always be possible to reach the final position though. See [method get_final_position]. + Returns [code]true[/code] if the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </method> <method name="set_avoidance_layer_value"> @@ -180,7 +180,7 @@ The distance to search for other agents. </member> <member name="path_desired_distance" type="float" setter="set_path_desired_distance" getter="get_path_desired_distance" default="20.0"> - The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the next point on each physics frame update. + The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to it leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot the distance to the next point on each physics frame update. </member> <member name="path_max_distance" type="float" setter="set_path_max_distance" getter="get_path_max_distance" default="100.0"> The maximum distance the agent is allowed away from the ideal path to the final position. This can happen due to trying to avoid collisions. When the maximum distance is exceeded, it recalculates the ideal path. @@ -199,7 +199,9 @@ Does not affect normal pathfinding. To change an actor's pathfinding radius bake [NavigationMesh] resources with a different [member NavigationMesh.agent_radius] property and use different navigation maps for each actor size. </member> <member name="target_desired_distance" type="float" setter="set_target_desired_distance" getter="get_target_desired_distance" default="10.0"> - The distance threshold before the final target point is considered to be reached. This allows agents to not have to hit the point of the final target exactly, but only to reach its general area. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the final target point on each physics frame update. + The distance threshold before the target is considered to be reached. On reaching the target, [signal target_reached] is emitted and navigation ends (see [method is_navigation_finished] and [signal navigation_finished]). + You can make navigation end early by setting this property to a value greater than [member path_desired_distance] (navigation will end before reaching the last waypoint). + You can also make navigation end closer to the target than each individual path position by setting this property to a value lower than [member path_desired_distance] (navigation won't immediately end when reaching the last waypoint). However, if the value set is too low, the agent will be stuck in a repath loop because it will constantly overshoot the distance to the target on each physics frame update. </member> <member name="target_position" type="Vector2" setter="set_target_position" getter="get_target_position" default="Vector2(0, 0)"> If set, a new navigation path from the current agent position to the [member target_position] is requested from the NavigationServer. @@ -218,7 +220,7 @@ <signal name="link_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a navigation link has been reached. + Signals that the agent reached a navigation link. Emitted when the agent moves within [member path_desired_distance] of the next position of the path when that position is a navigation link. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The start position of the link that was reached. - [code]type[/code]: Always [constant NavigationPathQueryResult2D.PATH_SEGMENT_TYPE_LINK]. @@ -230,7 +232,8 @@ </signal> <signal name="navigation_finished"> <description> - Emitted once per loaded path when the agent internal navigation path index reaches the last index of the loaded path array. The agent internal navigation path index can be received with [method get_current_navigation_path_index]. + Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path. + This signal will be emitted just after [signal target_reached] when the target is reachable. </description> </signal> <signal name="path_changed"> @@ -243,7 +246,9 @@ </signal> <signal name="target_reached"> <description> - Emitted once per loaded path when the agent's global position is the first time within [member target_desired_distance] to the [member target_position]. + Signals that the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. This signal is emitted only once per loaded path. + This signal will be emitted just before [signal navigation_finished] when the target is reachable. + It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </signal> <signal name="velocity_computed"> @@ -255,7 +260,7 @@ <signal name="waypoint_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a waypoint along the path has been reached. + Signals that the agent reached a waypoint. Emitted when the agent moves within [member path_desired_distance] of the next position of the path. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The position of the waypoint that was reached. - [code]type[/code]: The type of navigation primitive (region or link) that contains this waypoint. diff --git a/doc/classes/NavigationAgent3D.xml b/doc/classes/NavigationAgent3D.xml index ec9f679307..dd75cedf61 100644 --- a/doc/classes/NavigationAgent3D.xml +++ b/doc/classes/NavigationAgent3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationAgent3D" inherits="Node" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationAgent3D" inherits="Node" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A 3D agent used to pathfind to a position while avoiding obstacles. </brief_description> @@ -84,8 +84,8 @@ <method name="is_navigation_finished"> <return type="bool" /> <description> - Returns [code]true[/code] if the end of the currently loaded navigation path has been reached. - [b]Note:[/b] While true prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. + Returns [code]true[/code] if the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. + [b]Note:[/b] While [code]true[/code] prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. </description> </method> <method name="is_target_reachable"> @@ -97,7 +97,7 @@ <method name="is_target_reached" qualifiers="const"> <return type="bool" /> <description> - Returns true if [member target_position] is reached. It may not always be possible to reach the target position. It should always be possible to reach the final position though. See [method get_final_position]. + Returns [code]true[/code] if the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </method> <method name="set_avoidance_layer_value"> @@ -168,7 +168,7 @@ The height of the avoidance agent. Agents will ignore other agents or obstacles that are above or below their current position + height in 2D avoidance. Does nothing in 3D avoidance which uses radius spheres alone. </member> <member name="keep_y_velocity" type="bool" setter="set_keep_y_velocity" getter="get_keep_y_velocity" default="true"> - If [code]true[/code], and the agent uses 2D avoidance, it will remember the set y-axis velocity and reapply it after the avoidance step. While 2D avoidance has no y-axis and simulates on a flat plane this setting can help mitigate the most obvious clipping on uneven 3D geometry. + If [code]true[/code], and the agent uses 2D avoidance, it will remember the set y-axis velocity and reapply it after the avoidance step. While 2D avoidance has no y-axis and simulates on a flat plane this setting can help to soften the most obvious clipping on uneven 3D geometry. </member> <member name="max_neighbors" type="int" setter="set_max_neighbors" getter="get_max_neighbors" default="10"> The maximum number of neighbors for the agent to consider. @@ -183,7 +183,7 @@ The distance to search for other agents. </member> <member name="path_desired_distance" type="float" setter="set_path_desired_distance" getter="get_path_desired_distance" default="1.0"> - The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the next point on each physics frame update. + The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to it leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot the distance to the next point on each physics frame update. </member> <member name="path_height_offset" type="float" setter="set_path_height_offset" getter="get_path_height_offset" default="0.0"> The height offset is subtracted from the y-axis value of any vector path position for this NavigationAgent. The NavigationAgent height offset does not change or influence the navigation mesh or pathfinding query result. Additional navigation maps that use regions with navigation meshes that the developer baked with appropriate agent radius or height values are required to support different-sized agents. @@ -205,7 +205,9 @@ Does not affect normal pathfinding. To change an actor's pathfinding radius bake [NavigationMesh] resources with a different [member NavigationMesh.agent_radius] property and use different navigation maps for each actor size. </member> <member name="target_desired_distance" type="float" setter="set_target_desired_distance" getter="get_target_desired_distance" default="1.0"> - The distance threshold before the final target point is considered to be reached. This allows agents to not have to hit the point of the final target exactly, but only to reach its general area. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the final target point on each physics frame update. + The distance threshold before the target is considered to be reached. On reaching the target, [signal target_reached] is emitted and navigation ends (see [method is_navigation_finished] and [signal navigation_finished]). + You can make navigation end early by setting this property to a value greater than [member path_desired_distance] (navigation will end before reaching the last waypoint). + You can also make navigation end closer to the target than each individual path position by setting this property to a value lower than [member path_desired_distance] (navigation won't immediately end when reaching the last waypoint). However, if the value set is too low, the agent will be stuck in a repath loop because it will constantly overshoot the distance to the target on each physics frame update. </member> <member name="target_position" type="Vector3" setter="set_target_position" getter="get_target_position" default="Vector3(0, 0, 0)"> If set, a new navigation path from the current agent position to the [member target_position] is requested from the NavigationServer. @@ -228,7 +230,7 @@ <signal name="link_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a navigation link has been reached. + Signals that the agent reached a navigation link. Emitted when the agent moves within [member path_desired_distance] of the next position of the path when that position is a navigation link. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The start position of the link that was reached. - [code]type[/code]: Always [constant NavigationPathQueryResult3D.PATH_SEGMENT_TYPE_LINK]. @@ -240,7 +242,8 @@ </signal> <signal name="navigation_finished"> <description> - Emitted once per loaded path when the agent internal navigation path index reaches the last index of the loaded path array. The agent internal navigation path index can be received with [method get_current_navigation_path_index]. + Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path. + This signal will be emitted just after [signal target_reached] when the target is reachable. </description> </signal> <signal name="path_changed"> @@ -253,7 +256,9 @@ </signal> <signal name="target_reached"> <description> - Emitted once per loaded path when the agent's global position is the first time within [member target_desired_distance] to the [member target_position]. + Signals that the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. This signal is emitted only once per loaded path. + This signal will be emitted just before [signal navigation_finished] when the target is reachable. + It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </signal> <signal name="velocity_computed"> @@ -265,7 +270,7 @@ <signal name="waypoint_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a waypoint along the path has been reached. + Signals that the agent reached a waypoint. Emitted when the agent moves within [member path_desired_distance] of the next position of the path. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The position of the waypoint that was reached. - [code]type[/code]: The type of navigation primitive (region or link) that contains this waypoint. diff --git a/doc/classes/NavigationLink2D.xml b/doc/classes/NavigationLink2D.xml index b12051b4f4..0892c9ec44 100644 --- a/doc/classes/NavigationLink2D.xml +++ b/doc/classes/NavigationLink2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationLink2D" inherits="Node2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationLink2D" inherits="Node2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A link between two positions on [NavigationRegion2D]s that agents can be routed through. </brief_description> @@ -29,6 +29,12 @@ Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [param layer_number] between 1 and 32. </description> </method> + <method name="get_rid" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of this link on the [NavigationServer2D]. + </description> + </method> <method name="set_global_end_position"> <return type="void" /> <param index="0" name="position" type="Vector2" /> diff --git a/doc/classes/NavigationLink3D.xml b/doc/classes/NavigationLink3D.xml index 90eaaaee6d..0fcc106beb 100644 --- a/doc/classes/NavigationLink3D.xml +++ b/doc/classes/NavigationLink3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationLink3D" inherits="Node3D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationLink3D" inherits="Node3D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A link between two positions on [NavigationRegion3D]s that agents can be routed through. </brief_description> @@ -29,6 +29,12 @@ Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [param layer_number] between 1 and 32. </description> </method> + <method name="get_rid" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of this link on the [NavigationServer3D]. + </description> + </method> <method name="set_global_end_position"> <return type="void" /> <param index="0" name="position" type="Vector3" /> diff --git a/doc/classes/NavigationMesh.xml b/doc/classes/NavigationMesh.xml index a76e739c23..42ef354bc8 100644 --- a/doc/classes/NavigationMesh.xml +++ b/doc/classes/NavigationMesh.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationMesh" inherits="Resource" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationMesh" inherits="Resource" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A navigation mesh that defines traversable areas and obstacles. </brief_description> @@ -96,6 +96,11 @@ The distance to erode/shrink the walkable area of the heightfield away from obstructions. [b]Note:[/b] While baking, this value will be rounded up to the nearest multiple of [member cell_size]. </member> + <member name="border_size" type="float" setter="set_border_size" getter="get_border_size" default="0.0"> + The size of the non-navigable border around the bake bounding area. + In conjunction with the [member filter_baking_aabb] and a [member edge_max_error] value at [code]1.0[/code] or below the border size can be used to bake tile aligned navigation meshes without the tile edges being shrunk by [member agent_radius]. + [b]Note:[/b] While baking and not zero, this value will be rounded up to the nearest multiple of [member cell_size]. + </member> <member name="cell_height" type="float" setter="set_cell_height" getter="get_cell_height" default="0.25"> The cell height used to rasterize the navigation mesh vertices on the Y axis. Must match with the cell height on the navigation map. </member> diff --git a/doc/classes/NavigationMeshGenerator.xml b/doc/classes/NavigationMeshGenerator.xml index 0997354aff..2ff791d5ee 100644 --- a/doc/classes/NavigationMeshGenerator.xml +++ b/doc/classes/NavigationMeshGenerator.xml @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationMeshGenerator" inherits="Object" is_deprecated="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationMeshGenerator" inherits="Object" deprecated="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Helper class for creating and clearing navigation meshes. </brief_description> <description> This class is responsible for creating and clearing 3D navigation meshes used as [NavigationMesh] resources inside [NavigationRegion3D]. The [NavigationMeshGenerator] has very limited to no use for 2D as the navigation mesh baking process expects 3D node types and 3D source geometry to parse. - The entire navigation mesh baking is best done in a separate thread as the voxelization, collision tests and mesh optimization steps involved are very performance and time hungry operations. + The entire navigation mesh baking is best done in a separate thread as the voxelization, collision tests and mesh optimization steps involved are very slow and performance-intensive operations. Navigation mesh baking happens in multiple steps and the result depends on 3D source geometry and properties of the [NavigationMesh] resource. In the first step, starting from a root node and depending on [NavigationMesh] properties all valid 3D source geometry nodes are collected from the [SceneTree]. Second, all collected nodes are parsed for their relevant 3D geometry data and a combined 3D mesh is build. Due to the many different types of parsable objects, from normal [MeshInstance3D]s to [CSGShape3D]s or various [CollisionObject3D]s, some operations to collect geometry data can trigger [RenderingServer] and [PhysicsServer3D] synchronizations. Server synchronization can have a negative effect on baking time or framerate as it often involves [Mutex] locking for thread security. Many parsable objects and the continuous synchronization with other threaded Servers can increase the baking time significantly. On the other hand only a few but very large and complex objects will take some time to prepare for the Servers which can noticeably stall the next frame render. As a general rule the total number of parsable objects and their individual size and complexity should be balanced to avoid framerate issues or very long baking times. The combined mesh is then passed to the Recast Navigation Object to test the source geometry for walkable terrain suitable to [NavigationMesh] agent properties by creating a voxel world around the meshes bounding area. The finalized navigation mesh is then returned and stored inside the [NavigationMesh] for use as a resource inside [NavigationRegion3D] nodes. [b]Note:[/b] Using meshes to not only define walkable surfaces but also obstruct navigation baking does not always work. The navigation baking has no concept of what is a geometry "inside" when dealing with mesh source geometry and this is intentional. Depending on current baking parameters, as soon as the obstructing mesh is large enough to fit a navigation mesh area inside, the baking will generate navigation mesh areas that are inside the obstructing source geometry mesh. @@ -14,12 +14,12 @@ <link title="Using NavigationMeshes">$DOCS_URL/tutorials/navigation/navigation_using_navigationmeshes.html</link> </tutorials> <methods> - <method name="bake" is_deprecated="true"> + <method name="bake" deprecated="This method is deprecated due to core threading changes. To upgrade existing code, first create a [NavigationMeshSourceGeometryData3D] resource. Use this resource with [method parse_source_geometry_data] to parse the [SceneTree] for nodes that should contribute to the navigation mesh baking. The [SceneTree] parsing needs to happen on the main thread. After the parsing is finished use the resource with [method bake_from_source_geometry_data] to bake a navigation mesh."> <return type="void" /> <param index="0" name="navigation_mesh" type="NavigationMesh" /> <param index="1" name="root_node" type="Node" /> <description> - The bake function is deprecated due to core threading changes. To upgrade existing code, first create a [NavigationMeshSourceGeometryData3D] resource. Use this resource with [method parse_source_geometry_data] to parse the SceneTree for nodes that should contribute to the navigation mesh baking. The SceneTree parsing needs to happen on the main thread. After the parsing is finished use the resource with [method bake_from_source_geometry_data] to bake a navigation mesh. + Bakes the [param navigation_mesh] with source geometry collected starting from the [param root_node]. </description> </method> <method name="bake_from_source_geometry_data"> diff --git a/doc/classes/NavigationMeshSourceGeometryData2D.xml b/doc/classes/NavigationMeshSourceGeometryData2D.xml index 4bf5213da7..609877fadc 100644 --- a/doc/classes/NavigationMeshSourceGeometryData2D.xml +++ b/doc/classes/NavigationMeshSourceGeometryData2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationMeshSourceGeometryData2D" inherits="Resource" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationMeshSourceGeometryData2D" inherits="Resource" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Container for parsed source geometry data used in navigation mesh baking. </brief_description> @@ -16,6 +16,14 @@ Adds the outline points of a shape as obstructed area. </description> </method> + <method name="add_projected_obstruction"> + <return type="void" /> + <param index="0" name="vertices" type="PackedVector2Array" /> + <param index="1" name="carve" type="bool" /> + <description> + Adds a projected obstruction shape to the source geometry. If [param carve] is [code]true[/code] the carved shape will not be affected by additional offsets (e.g. agent radius) of the navigation mesh baking process. + </description> + </method> <method name="add_traversable_outline"> <return type="void" /> <param index="0" name="shape_outline" type="PackedVector2Array" /> @@ -29,12 +37,26 @@ Clears the internal data. </description> </method> + <method name="clear_projected_obstructions"> + <return type="void" /> + <description> + Clears all projected obstructions. + </description> + </method> <method name="get_obstruction_outlines" qualifiers="const"> <return type="PackedVector2Array[]" /> <description> Returns all the obstructed area outlines arrays. </description> </method> + <method name="get_projected_obstructions" qualifiers="const"> + <return type="Array" /> + <description> + Returns the projected obstructions as an [Array] of dictionaries. Each [Dictionary] contains the following entries: + - [code]vertices[/code] - A [PackedFloat32Array] that defines the outline points of the projected shape. + - [code]carve[/code] - A [bool] that defines how the projected shape affects the navigation mesh baking. If [code]true[/code] the projected shape will not be affected by addition offsets, e.g. agent radius. + </description> + </method> <method name="get_traversable_outlines" qualifiers="const"> <return type="PackedVector2Array[]" /> <description> @@ -47,6 +69,13 @@ Returns [code]true[/code] when parsed source geometry data exists. </description> </method> + <method name="merge"> + <return type="void" /> + <param index="0" name="other_geometry" type="NavigationMeshSourceGeometryData2D" /> + <description> + Adds the geometry data of another [NavigationMeshSourceGeometryData2D] to the navigation mesh baking data. + </description> + </method> <method name="set_obstruction_outlines"> <return type="void" /> <param index="0" name="obstruction_outlines" type="PackedVector2Array[]" /> @@ -54,6 +83,19 @@ Sets all the obstructed area outlines arrays. </description> </method> + <method name="set_projected_obstructions"> + <return type="void" /> + <param index="0" name="projected_obstructions" type="Array" /> + <description> + Sets the projected obstructions with an Array of Dictionaries with the following key value pairs: + [codeblocks] + [gdscript] + "vertices" : PackedFloat32Array + "carve" : bool + [/gdscript] + [/codeblocks] + </description> + </method> <method name="set_traversable_outlines"> <return type="void" /> <param index="0" name="traversable_outlines" type="PackedVector2Array[]" /> diff --git a/doc/classes/NavigationMeshSourceGeometryData3D.xml b/doc/classes/NavigationMeshSourceGeometryData3D.xml index dad3623416..322e2e7c66 100644 --- a/doc/classes/NavigationMeshSourceGeometryData3D.xml +++ b/doc/classes/NavigationMeshSourceGeometryData3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationMeshSourceGeometryData3D" inherits="Resource" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationMeshSourceGeometryData3D" inherits="Resource" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Container for parsed source geometry data used in navigation mesh baking. </brief_description> @@ -33,18 +33,44 @@ Adds an [Array] the size of [constant Mesh.ARRAY_MAX] and with vertices at index [constant Mesh.ARRAY_VERTEX] and indices at index [constant Mesh.ARRAY_INDEX] to the navigation mesh baking data. The array must have valid triangulated mesh data to be considered. Since [NavigationMesh] resources have no transform, all vertex positions need to be offset by the node's transform using [param xform]. </description> </method> + <method name="add_projected_obstruction"> + <return type="void" /> + <param index="0" name="vertices" type="PackedVector3Array" /> + <param index="1" name="elevation" type="float" /> + <param index="2" name="height" type="float" /> + <param index="3" name="carve" type="bool" /> + <description> + Adds a projected obstruction shape to the source geometry. The [param vertices] are considered projected on a xz-axes plane, placed at the global y-axis [param elevation] and extruded by [param height]. If [param carve] is [code]true[/code] the carved shape will not be affected by additional offsets (e.g. agent radius) of the navigation mesh baking process. + </description> + </method> <method name="clear"> <return type="void" /> <description> Clears the internal data. </description> </method> + <method name="clear_projected_obstructions"> + <return type="void" /> + <description> + Clears all projected obstructions. + </description> + </method> <method name="get_indices" qualifiers="const"> <return type="PackedInt32Array" /> <description> Returns the parsed source geometry data indices array. </description> </method> + <method name="get_projected_obstructions" qualifiers="const"> + <return type="Array" /> + <description> + Returns the projected obstructions as an [Array] of dictionaries. Each [Dictionary] contains the following entries: + - [code]vertices[/code] - A [PackedFloat32Array] that defines the outline points of the projected shape. + - [code]elevation[/code] - A [float] that defines the projected shape placement on the y-axis. + - [code]height[/code] - A [float] that defines how much the projected shape is extruded along the y-axis. + - [code]carve[/code] - A [bool] that defines how the obstacle affects the navigation mesh baking. If [code]true[/code] the projected shape will not be affected by addition offsets, e.g. agent radius. + </description> + </method> <method name="get_vertices" qualifiers="const"> <return type="PackedFloat32Array" /> <description> @@ -57,6 +83,13 @@ Returns [code]true[/code] when parsed source geometry data exists. </description> </method> + <method name="merge"> + <return type="void" /> + <param index="0" name="other_geometry" type="NavigationMeshSourceGeometryData3D" /> + <description> + Adds the geometry data of another [NavigationMeshSourceGeometryData3D] to the navigation mesh baking data. + </description> + </method> <method name="set_indices"> <return type="void" /> <param index="0" name="indices" type="PackedInt32Array" /> @@ -65,6 +98,21 @@ [b]Warning:[/b] Inappropriate data can crash the baking process of the involved third-party libraries. </description> </method> + <method name="set_projected_obstructions"> + <return type="void" /> + <param index="0" name="projected_obstructions" type="Array" /> + <description> + Sets the projected obstructions with an Array of Dictionaries with the following key value pairs: + [codeblocks] + [gdscript] + "vertices" : PackedFloat32Array + "elevation" : float + "height" : float + "carve" : bool + [/gdscript] + [/codeblocks] + </description> + </method> <method name="set_vertices"> <return type="void" /> <param index="0" name="vertices" type="PackedFloat32Array" /> diff --git a/doc/classes/NavigationObstacle2D.xml b/doc/classes/NavigationObstacle2D.xml index 1eb18984a6..12205e2ac3 100644 --- a/doc/classes/NavigationObstacle2D.xml +++ b/doc/classes/NavigationObstacle2D.xml @@ -1,13 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationObstacle2D" inherits="Node2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationObstacle2D" inherits="Node2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - 2D Obstacle used in navigation to constrain avoidance controlled agents outside or inside an area. + 2D obstacle used to affect navigation mesh baking or constrain velocities of avoidance controlled agents. </brief_description> <description> - 2D Obstacle used in navigation to constrain avoidance controlled agents outside or inside an area. The obstacle needs a navigation map and outline vertices defined to work correctly. - If the obstacle's vertices are winded in clockwise order, avoidance agents will be pushed in by the obstacle, otherwise, avoidance agents will be pushed out. Outlines must not cross or overlap. - Obstacles are [b]not[/b] a replacement for a (re)baked navigation mesh. Obstacles [b]don't[/b] change the resulting path from the pathfinding, obstacles only affect the navigation avoidance agent movement by altering the suggested velocity of the avoidance agent. - Obstacles using vertices can warp to a new position but should not moved every frame as each move requires a rebuild of the avoidance map. + An obstacle needs a navigation map and outline [member vertices] defined to work correctly. The outlines can not cross or overlap. + Obstacles can be included in the navigation mesh baking process when [member affect_navigation_mesh] is enabled. They do not add walkable geometry, instead their role is to discard other source geometry inside the shape. This can be used to prevent navigation mesh from appearing in unwanted places. If [member carve_navigation_mesh] is enabled the baked shape will not be affected by offsets of the navigation mesh baking, e.g. the agent radius. + With [member avoidance_enabled] the obstacle can constrain the avoidance velocities of avoidance using agents. If the obstacle's vertices are wound in clockwise order, avoidance agents will be pushed in by the obstacle, otherwise, avoidance agents will be pushed out. Obstacles using vertices and avoidance can warp to a new position but should not be moved every single frame as each change requires a rebuild of the avoidance map. </description> <tutorials> <link title="Using NavigationObstacles">$DOCS_URL/tutorials/navigation/navigation_using_navigationobstacles.html</link> @@ -49,12 +48,20 @@ </method> </methods> <members> + <member name="affect_navigation_mesh" type="bool" setter="set_affect_navigation_mesh" getter="get_affect_navigation_mesh" default="false"> + If enabled and parsed in a navigation mesh baking process the obstacle will discard source geometry inside its [member vertices] defined shape. + </member> <member name="avoidance_enabled" type="bool" setter="set_avoidance_enabled" getter="get_avoidance_enabled" default="true"> If [code]true[/code] the obstacle affects avoidance using agents. </member> <member name="avoidance_layers" type="int" setter="set_avoidance_layers" getter="get_avoidance_layers" default="1"> A bitfield determining the avoidance layers for this obstacle. Agents with a matching bit on the their avoidance mask will avoid this obstacle. </member> + <member name="carve_navigation_mesh" type="bool" setter="set_carve_navigation_mesh" getter="get_carve_navigation_mesh" default="false"> + If enabled the obstacle vertices will carve into the baked navigation mesh with the shape unaffected by additional offsets (e.g. agent radius). + It will still be affected by further postprocessing of the baking process, like edge and polygon simplification. + Requires [member affect_navigation_mesh] to be enabled. + </member> <member name="radius" type="float" setter="set_radius" getter="get_radius" default="0.0"> Sets the avoidance radius for the obstacle. </member> diff --git a/doc/classes/NavigationObstacle3D.xml b/doc/classes/NavigationObstacle3D.xml index 141442eaf0..bc6dbabc0e 100644 --- a/doc/classes/NavigationObstacle3D.xml +++ b/doc/classes/NavigationObstacle3D.xml @@ -1,13 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationObstacle3D" inherits="Node3D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationObstacle3D" inherits="Node3D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - 3D Obstacle used in navigation to constrain avoidance controlled agents outside or inside an area. + 3D obstacle used to affect navigation mesh baking or constrain velocities of avoidance controlled agents. </brief_description> <description> - 3D Obstacle used in navigation to constrain avoidance controlled agents outside or inside an area. The obstacle needs a navigation map and outline vertices defined to work correctly. - If the obstacle's vertices are winded in clockwise order, avoidance agents will be pushed in by the obstacle, otherwise, avoidance agents will be pushed out. Outlines must not cross or overlap. - Obstacles are [b]not[/b] a replacement for a (re)baked navigation mesh. Obstacles [b]don't[/b] change the resulting path from the pathfinding, obstacles only affect the navigation avoidance agent movement by altering the suggested velocity of the avoidance agent. - Obstacles using vertices can warp to a new position but should not moved every frame as each move requires a rebuild of the avoidance map. + An obstacle needs a navigation map and outline [member vertices] defined to work correctly. The outlines can not cross or overlap and are restricted to a plane projection. This means the y-axis of the vertices is ignored, instead the obstacle's global y-axis position is used for placement. The projected shape is extruded by the obstacles height along the y-axis. + Obstacles can be included in the navigation mesh baking process when [member affect_navigation_mesh] is enabled. They do not add walkable geometry, instead their role is to discard other source geometry inside the shape. This can be used to prevent navigation mesh from appearing in unwanted places, e.g. inside "solid" geometry or on top of it. If [member carve_navigation_mesh] is enabled the baked shape will not be affected by offsets of the navigation mesh baking, e.g. the agent radius. + With [member avoidance_enabled] the obstacle can constrain the avoidance velocities of avoidance using agents. If the obstacle's vertices are wound in clockwise order, avoidance agents will be pushed in by the obstacle, otherwise, avoidance agents will be pushed out. Obstacles using vertices and avoidance can warp to a new position but should not be moved every single frame as each change requires a rebuild of the avoidance map. </description> <tutorials> <link title="Using NavigationObstacles">$DOCS_URL/tutorials/navigation/navigation_using_navigationobstacles.html</link> @@ -49,12 +48,20 @@ </method> </methods> <members> + <member name="affect_navigation_mesh" type="bool" setter="set_affect_navigation_mesh" getter="get_affect_navigation_mesh" default="false"> + If enabled and parsed in a navigation mesh baking process the obstacle will discard source geometry inside its [member vertices] and [member height] defined shape. + </member> <member name="avoidance_enabled" type="bool" setter="set_avoidance_enabled" getter="get_avoidance_enabled" default="true"> If [code]true[/code] the obstacle affects avoidance using agents. </member> <member name="avoidance_layers" type="int" setter="set_avoidance_layers" getter="get_avoidance_layers" default="1"> A bitfield determining the avoidance layers for this obstacle. Agents with a matching bit on the their avoidance mask will avoid this obstacle. </member> + <member name="carve_navigation_mesh" type="bool" setter="set_carve_navigation_mesh" getter="get_carve_navigation_mesh" default="false"> + If enabled the obstacle vertices will carve into the baked navigation mesh with the shape unaffected by additional offsets (e.g. agent radius). + It will still be affected by further postprocessing of the baking process, like edge and polygon simplification. + Requires [member affect_navigation_mesh] to be enabled. + </member> <member name="height" type="float" setter="set_height" getter="get_height" default="1.0"> Sets the obstacle height used in 2D avoidance. 2D avoidance using agent's ignore obstacles that are below or above them. </member> diff --git a/doc/classes/NavigationPathQueryParameters2D.xml b/doc/classes/NavigationPathQueryParameters2D.xml index 74cf4bdb75..7d9ecf61b0 100644 --- a/doc/classes/NavigationPathQueryParameters2D.xml +++ b/doc/classes/NavigationPathQueryParameters2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationPathQueryParameters2D" inherits="RefCounted" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationPathQueryParameters2D" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Provides parameters for 2D navigation path queries. </brief_description> diff --git a/doc/classes/NavigationPathQueryParameters3D.xml b/doc/classes/NavigationPathQueryParameters3D.xml index 2a366c0498..862f8a8347 100644 --- a/doc/classes/NavigationPathQueryParameters3D.xml +++ b/doc/classes/NavigationPathQueryParameters3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationPathQueryParameters3D" inherits="RefCounted" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationPathQueryParameters3D" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Provides parameters for 3D navigation path queries. </brief_description> diff --git a/doc/classes/NavigationPathQueryResult2D.xml b/doc/classes/NavigationPathQueryResult2D.xml index e02133cfba..e1ef2ee7de 100644 --- a/doc/classes/NavigationPathQueryResult2D.xml +++ b/doc/classes/NavigationPathQueryResult2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationPathQueryResult2D" inherits="RefCounted" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationPathQueryResult2D" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Represents the result of a 2D pathfinding query. </brief_description> diff --git a/doc/classes/NavigationPathQueryResult3D.xml b/doc/classes/NavigationPathQueryResult3D.xml index 9631c6a644..1cda3e64d5 100644 --- a/doc/classes/NavigationPathQueryResult3D.xml +++ b/doc/classes/NavigationPathQueryResult3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationPathQueryResult3D" inherits="RefCounted" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationPathQueryResult3D" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Represents the result of a 3D pathfinding query. </brief_description> diff --git a/doc/classes/NavigationPolygon.xml b/doc/classes/NavigationPolygon.xml index e0ad6032de..9c4e8169b0 100644 --- a/doc/classes/NavigationPolygon.xml +++ b/doc/classes/NavigationPolygon.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationPolygon" inherits="Resource" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationPolygon" inherits="Resource" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A 2D navigation mesh that describes a traversable surface for pathfinding. </brief_description> @@ -132,11 +132,10 @@ Returns a [PackedVector2Array] containing all the vertices being used to create the polygons. </description> </method> - <method name="make_polygons_from_outlines" is_deprecated="true"> + <method name="make_polygons_from_outlines" deprecated="Use [method NavigationServer2D.parse_source_geometry_data] and [method NavigationServer2D.bake_from_source_geometry_data] instead."> <return type="void" /> <description> Creates polygons from the outlines added in the editor or by script. - [i]Deprecated.[/i] This function is deprecated, and might be removed in a future release. Use [method NavigationServer2D.parse_source_geometry_data] and [method NavigationServer2D.bake_from_source_geometry_data] instead. </description> </method> <method name="remove_outline"> @@ -174,6 +173,16 @@ <member name="agent_radius" type="float" setter="set_agent_radius" getter="get_agent_radius" default="10.0"> The distance to erode/shrink the walkable surface when baking the navigation mesh. </member> + <member name="baking_rect" type="Rect2" setter="set_baking_rect" getter="get_baking_rect" default="Rect2(0, 0, 0, 0)"> + If the baking [Rect2] has an area the navigation mesh baking will be restricted to its enclosing area. + </member> + <member name="baking_rect_offset" type="Vector2" setter="set_baking_rect_offset" getter="get_baking_rect_offset" default="Vector2(0, 0)"> + The position offset applied to the [member baking_rect] [Rect2]. + </member> + <member name="border_size" type="float" setter="set_border_size" getter="get_border_size" default="0.0"> + The size of the non-navigable border around the bake bounding area defined by the [member baking_rect] [Rect2]. + In conjunction with the [member baking_rect] the border size can be used to bake tile aligned navigation meshes without the tile edges being shrunk by [member agent_radius]. + </member> <member name="cell_size" type="float" setter="set_cell_size" getter="get_cell_size" default="1.0"> The cell size used to rasterize the navigation mesh vertices. Must match with the cell size on the navigation map. </member> diff --git a/doc/classes/NavigationRegion2D.xml b/doc/classes/NavigationRegion2D.xml index ef660305f4..c490620fc0 100644 --- a/doc/classes/NavigationRegion2D.xml +++ b/doc/classes/NavigationRegion2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationRegion2D" inherits="Node2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationRegion2D" inherits="Node2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A traversable 2D region that [NavigationAgent2D]s can use for pathfinding. </brief_description> @@ -43,12 +43,24 @@ Returns the current navigation map [RID] used by this region. </description> </method> - <method name="get_region_rid" qualifiers="const"> + <method name="get_region_rid" qualifiers="const" deprecated="Use [method get_rid] instead."> + <return type="RID" /> + <description> + Returns the [RID] of this region on the [NavigationServer2D]. + </description> + </method> + <method name="get_rid" qualifiers="const"> <return type="RID" /> <description> Returns the [RID] of this region on the [NavigationServer2D]. Combined with [method NavigationServer2D.map_get_closest_point_owner] can be used to identify the [NavigationRegion2D] closest to a point on the merged navigation map. </description> </method> + <method name="is_baking" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] when the [NavigationPolygon] is being baked on a background thread. + </description> + </method> <method name="set_avoidance_layer_value"> <return type="void" /> <param index="0" name="layer_number" type="int" /> @@ -77,9 +89,8 @@ <member name="avoidance_layers" type="int" setter="set_avoidance_layers" getter="get_avoidance_layers" default="1"> A bitfield determining all avoidance layers for the avoidance constrain. </member> - <member name="constrain_avoidance" type="bool" setter="set_constrain_avoidance" getter="get_constrain_avoidance" default="false"> + <member name="constrain_avoidance" type="bool" setter="set_constrain_avoidance" getter="get_constrain_avoidance" default="false" experimental="When enabled, agents are known to get stuck on the navigation polygon corners and edges, especially at a high frame rate. Not recommended for use in production at this stage."> If [code]true[/code] constraints avoidance agent's with an avoidance mask bit that matches with a bit of the [member avoidance_layers] to the navigation polygon. Due to each navigation polygon outline creating an obstacle and each polygon edge creating an avoidance line constrain keep the navigation polygon shape as simple as possible for performance. - [b]Experimental:[/b] This is an experimental feature and should not be used in production as agent's can get stuck on the navigation polygon corners and edges especially at high frame rate. </member> <member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true"> Determines if the [NavigationRegion2D] is enabled or disabled. diff --git a/doc/classes/NavigationRegion3D.xml b/doc/classes/NavigationRegion3D.xml index 3257160485..ad31fd0632 100644 --- a/doc/classes/NavigationRegion3D.xml +++ b/doc/classes/NavigationRegion3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationRegion3D" inherits="Node3D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationRegion3D" inherits="Node3D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A traversable 3D region that [NavigationAgent3D]s can use for pathfinding. </brief_description> @@ -36,12 +36,24 @@ Returns the current navigation map [RID] used by this region. </description> </method> - <method name="get_region_rid" qualifiers="const"> + <method name="get_region_rid" qualifiers="const" deprecated="Use [method get_rid] instead."> + <return type="RID" /> + <description> + Returns the [RID] of this region on the [NavigationServer3D]. + </description> + </method> + <method name="get_rid" qualifiers="const"> <return type="RID" /> <description> Returns the [RID] of this region on the [NavigationServer3D]. Combined with [method NavigationServer3D.map_get_closest_point_owner] can be used to identify the [NavigationRegion3D] closest to a point on the merged navigation map. </description> </method> + <method name="is_baking" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] when the [NavigationMesh] is being baked on a background thread. + </description> + </method> <method name="set_navigation_layer_value"> <return type="void" /> <param index="0" name="layer_number" type="int" /> diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml index a25f048df3..91d69edf29 100644 --- a/doc/classes/NavigationServer2D.xml +++ b/doc/classes/NavigationServer2D.xml @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationServer2D" inherits="Object" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationServer2D" inherits="Object" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A server interface for low-level 2D navigation access. </brief_description> <description> NavigationServer2D is the server that handles navigation maps, regions and agents. It does not handle A* navigation from [AStar2D] or [AStarGrid2D]. - Maps are made up of regions, which are made of navigation polygons. Together, they define the traversable areas in the 2D world. + Maps are divided into regions, which are composed of navigation polygons. Together, they define the traversable areas in the 2D world. [b]Note:[/b] Most [NavigationServer2D] changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation-related nodes in the scene tree or made through scripts. For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than [code]edge_connection_margin[/code] to the respective other edge's vertex. You may assign navigation layers to regions with [method NavigationServer2D.region_set_navigation_layers], which then can be checked upon when requesting a path with [method NavigationServer2D.map_get_path]. This can be used to allow or deny certain areas for some objects. @@ -31,6 +31,27 @@ Return [code]true[/code] if the specified [param agent] uses avoidance. </description> </method> + <method name="agent_get_avoidance_layers" qualifiers="const"> + <return type="int" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the [code]avoidance_layers[/code] bitmask of the specified [param agent]. + </description> + </method> + <method name="agent_get_avoidance_mask" qualifiers="const"> + <return type="int" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the [code]avoidance_mask[/code] bitmask of the specified [param agent]. + </description> + </method> + <method name="agent_get_avoidance_priority" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the [code]avoidance_priority[/code] of the specified [param agent]. + </description> + </method> <method name="agent_get_map" qualifiers="const"> <return type="RID" /> <param index="0" name="agent" type="RID" /> @@ -38,6 +59,27 @@ Returns the navigation map [RID] the requested [param agent] is currently assigned to. </description> </method> + <method name="agent_get_max_neighbors" qualifiers="const"> + <return type="int" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the maximum number of other agents the specified [param agent] takes into account in the navigation. + </description> + </method> + <method name="agent_get_max_speed" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the maximum speed of the specified [param agent]. + </description> + </method> + <method name="agent_get_neighbor_distance" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the maximum distance to other agents the specified [param agent] takes into account in the navigation. + </description> + </method> <method name="agent_get_paused" qualifiers="const"> <return type="bool" /> <param index="0" name="agent" type="RID" /> @@ -45,6 +87,48 @@ Returns [code]true[/code] if the specified [param agent] is paused. </description> </method> + <method name="agent_get_position" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the position of the specified [param agent] in world space. + </description> + </method> + <method name="agent_get_radius" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the radius of the specified [param agent]. + </description> + </method> + <method name="agent_get_time_horizon_agents" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the minimal amount of time for which the specified [param agent]'s velocities that are computed by the simulation are safe with respect to other agents. + </description> + </method> + <method name="agent_get_time_horizon_obstacles" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the minimal amount of time for which the specified [param agent]'s velocities that are computed by the simulation are safe with respect to static avoidance obstacles. + </description> + </method> + <method name="agent_get_velocity" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the velocity of the specified [param agent]. + </description> + </method> + <method name="agent_has_avoidance_callback" qualifiers="const"> + <return type="bool" /> + <param index="0" name="agent" type="RID" /> + <description> + Return [code]true[/code] if the specified [param agent] has an avoidance callback. + </description> + </method> <method name="agent_is_map_changed" qualifiers="const"> <return type="bool" /> <param index="0" name="agent" type="RID" /> @@ -91,7 +175,7 @@ <param index="1" name="priority" type="float" /> <description> Set the agent's [code]avoidance_priority[/code] with a [param priority] between 0.0 (lowest priority) to 1.0 (highest priority). - The specified [param agent] does not adjust the velocity for other agents that would match the [code]avoidance_mask[/code] but have a lower [code] avoidance_priority[/code]. This in turn makes the other agents with lower priority adjust their velocities even more to avoid collision with this agent. + The specified [param agent] does not adjust the velocity for other agents that would match the [code]avoidance_mask[/code] but have a lower [code]avoidance_priority[/code]. This in turn makes the other agents with lower priority adjust their velocities even more to avoid collision with this agent. </description> </method> <method name="agent_set_map"> @@ -219,6 +303,13 @@ Returns all created navigation map [RID]s on the NavigationServer. This returns both 2D and 3D created navigation maps as there is technically no distinction between them. </description> </method> + <method name="is_baking_navigation_polygon" qualifiers="const"> + <return type="bool" /> + <param index="0" name="navigation_polygon" type="NavigationPolygon" /> + <description> + Returns [code]true[/code] when the provided navigation polygon is being baked on a background thread. + </description> + </method> <method name="link_create"> <return type="RID" /> <description> @@ -372,7 +463,7 @@ <description> This function immediately forces synchronization of the specified navigation [param map] [RID]. By default navigation maps are only synchronized at the end of each physics frame. This function can be used to immediately (re)calculate all the navigation meshes and region connections of the navigation map. This makes it possible to query a navigation path for a changed map immediately and in the same frame (multiple times if needed). Due to technical restrictions the current NavigationServer command queue will be flushed. This means all already queued update commands for this physics frame will be executed, even those intended for other maps, regions and agents not part of the specified map. The expensive computation of the navigation meshes and region connections of a map will only be done for the specified map. Other maps will receive the normal synchronization at the end of the physics frame. Should the specified map receive changes after the forced update it will update again as well when the other maps receive their update. - Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is untouched by this function and continues to happen for all maps and agents at the end of the physics frame. + Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is unaffected by this function and continues to happen for all maps and agents at the end of the physics frame. [b]Note:[/b] With great power comes great responsibility. This function should only be used by users that really know what they are doing and have a good reason for it. Forcing an immediate update of a navigation map requires locking the NavigationServer and flushing the entire NavigationServer command queue. Not only can this severely impact the performance of a game but it can also introduce bugs if used inappropriately without much foresight. </description> </method> @@ -413,6 +504,14 @@ Returns the edge connection margin of the map. The edge connection margin is a distance used to connect two regions. </description> </method> + <method name="map_get_iteration_id" qualifiers="const"> + <return type="int" /> + <param index="0" name="map" type="RID" /> + <description> + Returns the current iteration id of the navigation map. Every time the navigation map changes and synchronizes the iteration id increases. An iteration id of 0 means the navigation map has never synchronized. + [b]Note:[/b] The iteration id will wrap back to 1 after reaching its range limit. + </description> + </method> <method name="map_get_link_connection_radius" qualifiers="const"> <return type="float" /> <param index="0" name="map" type="RID" /> @@ -445,6 +544,17 @@ Returns the navigation path to reach the destination from the origin. [param navigation_layers] is a bitmask of all region navigation layers that are allowed to be in the path. </description> </method> + <method name="map_get_random_point" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="map" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all map region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all map regions, polygons, and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random region and a random polygon are picked (faster). + </description> + </method> <method name="map_get_regions" qualifiers="const"> <return type="RID[]" /> <param index="0" name="map" type="RID" /> @@ -519,6 +629,13 @@ Returns [code]true[/code] if the provided [param obstacle] has avoidance enabled. </description> </method> + <method name="obstacle_get_avoidance_layers" qualifiers="const"> + <return type="int" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the [code]avoidance_layers[/code] bitmask of the specified [param obstacle]. + </description> + </method> <method name="obstacle_get_map" qualifiers="const"> <return type="RID" /> <param index="0" name="obstacle" type="RID" /> @@ -533,6 +650,34 @@ Returns [code]true[/code] if the specified [param obstacle] is paused. </description> </method> + <method name="obstacle_get_position" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the position of the specified [param obstacle] in world space. + </description> + </method> + <method name="obstacle_get_radius" qualifiers="const"> + <return type="float" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the radius of the specified dynamic [param obstacle]. + </description> + </method> + <method name="obstacle_get_velocity" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the velocity of the specified dynamic [param obstacle]. + </description> + </method> + <method name="obstacle_get_vertices" qualifiers="const"> + <return type="PackedVector2Array" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the outline vertices for the specified [param obstacle]. + </description> + </method> <method name="obstacle_set_avoidance_enabled"> <return type="void" /> <param index="0" name="obstacle" type="RID" /> @@ -681,6 +826,24 @@ Returns the [code]ObjectID[/code] of the object which manages this region. </description> </method> + <method name="region_get_random_point" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="region" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all region polygons and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random polygon and face is picked (faster). + </description> + </method> + <method name="region_get_transform" qualifiers="const"> + <return type="Transform2D" /> + <param index="0" name="region" type="RID" /> + <description> + Returns the global transformation of this [param region]. + </description> + </method> <method name="region_get_travel_cost" qualifiers="const"> <return type="float" /> <param index="0" name="region" type="RID" /> diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml index b56b86f435..29d9f5424a 100644 --- a/doc/classes/NavigationServer3D.xml +++ b/doc/classes/NavigationServer3D.xml @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="NavigationServer3D" inherits="Object" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="NavigationServer3D" inherits="Object" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A server interface for low-level 3D navigation access. </brief_description> <description> NavigationServer3D is the server that handles navigation maps, regions and agents. It does not handle A* navigation from [AStar3D]. - Maps are made up of regions, which are made of navigation meshes. Together, they define the navigable areas in the 3D world. + Maps are divided into regions, which are composed of navigation meshes. Together, they define the navigable areas in the 3D world. [b]Note:[/b] Most [NavigationServer3D] changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation-related nodes in the scene tree or made through scripts. For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than [code]edge_connection_margin[/code] to the respective other edge's vertex. You may assign navigation layers to regions with [method NavigationServer3D.region_set_navigation_layers], which then can be checked upon when requesting a path with [method NavigationServer3D.map_get_path]. This can be used to allow or deny certain areas for some objects. @@ -31,6 +31,34 @@ Returns [code]true[/code] if the provided [param agent] has avoidance enabled. </description> </method> + <method name="agent_get_avoidance_layers" qualifiers="const"> + <return type="int" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the [code]avoidance_layers[/code] bitmask of the specified [param agent]. + </description> + </method> + <method name="agent_get_avoidance_mask" qualifiers="const"> + <return type="int" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the [code]avoidance_mask[/code] bitmask of the specified [param agent]. + </description> + </method> + <method name="agent_get_avoidance_priority" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the [code]avoidance_priority[/code] of the specified [param agent]. + </description> + </method> + <method name="agent_get_height" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the [code]height[/code] of the specified [param agent]. + </description> + </method> <method name="agent_get_map" qualifiers="const"> <return type="RID" /> <param index="0" name="agent" type="RID" /> @@ -38,6 +66,27 @@ Returns the navigation map [RID] the requested [param agent] is currently assigned to. </description> </method> + <method name="agent_get_max_neighbors" qualifiers="const"> + <return type="int" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the maximum number of other agents the specified [param agent] takes into account in the navigation. + </description> + </method> + <method name="agent_get_max_speed" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the maximum speed of the specified [param agent]. + </description> + </method> + <method name="agent_get_neighbor_distance" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the maximum distance to other agents the specified [param agent] takes into account in the navigation. + </description> + </method> <method name="agent_get_paused" qualifiers="const"> <return type="bool" /> <param index="0" name="agent" type="RID" /> @@ -45,6 +94,34 @@ Returns [code]true[/code] if the specified [param agent] is paused. </description> </method> + <method name="agent_get_position" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the position of the specified [param agent] in world space. + </description> + </method> + <method name="agent_get_radius" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the radius of the specified [param agent]. + </description> + </method> + <method name="agent_get_time_horizon_agents" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the minimal amount of time for which the specified [param agent]'s velocities that are computed by the simulation are safe with respect to other agents. + </description> + </method> + <method name="agent_get_time_horizon_obstacles" qualifiers="const"> + <return type="float" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the minimal amount of time for which the specified [param agent]'s velocities that are computed by the simulation are safe with respect to static avoidance obstacles. + </description> + </method> <method name="agent_get_use_3d_avoidance" qualifiers="const"> <return type="bool" /> <param index="0" name="agent" type="RID" /> @@ -52,6 +129,20 @@ Returns [code]true[/code] if the provided [param agent] uses avoidance in 3D space Vector3(x,y,z) instead of horizontal 2D Vector2(x,y) / Vector3(x,0.0,z). </description> </method> + <method name="agent_get_velocity" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="agent" type="RID" /> + <description> + Returns the velocity of the specified [param agent]. + </description> + </method> + <method name="agent_has_avoidance_callback" qualifiers="const"> + <return type="bool" /> + <param index="0" name="agent" type="RID" /> + <description> + Return [code]true[/code] if the specified [param agent] has an avoidance callback. + </description> + </method> <method name="agent_is_map_changed" qualifiers="const"> <return type="bool" /> <param index="0" name="agent" type="RID" /> @@ -98,7 +189,7 @@ <param index="1" name="priority" type="float" /> <description> Set the agent's [code]avoidance_priority[/code] with a [param priority] between 0.0 (lowest priority) to 1.0 (highest priority). - The specified [param agent] does not adjust the velocity for other agents that would match the [code]avoidance_mask[/code] but have a lower [code] avoidance_priority[/code]. This in turn makes the other agents with lower priority adjust their velocities even more to avoid collision with this agent. + The specified [param agent] does not adjust the velocity for other agents that would match the [code]avoidance_mask[/code] but have a lower [code]avoidance_priority[/code]. This in turn makes the other agents with lower priority adjust their velocities even more to avoid collision with this agent. </description> </method> <method name="agent_set_height"> @@ -187,7 +278,7 @@ <param index="1" name="enabled" type="bool" /> <description> Sets if the agent uses the 2D avoidance or the 3D avoidance while avoidance is enabled. - If [code]true[/code] the agent calculates avoidance velocities in 3D for the xyz-axis, e.g. for games that take place in air, unterwater or space. The 3D using agent only avoids other 3D avoidance using agent's. The 3D using agent only reacts to radius based avoidance obstacles. The 3D using agent ignores any vertices based obstacles. The 3D using agent only avoids other 3D using agent's. + If [code]true[/code] the agent calculates avoidance velocities in 3D for the xyz-axis, e.g. for games that take place in air, underwater or space. The 3D using agent only avoids other 3D avoidance using agent's. The 3D using agent only reacts to radius based avoidance obstacles. The 3D using agent ignores any vertices based obstacles. The 3D using agent only avoids other 3D using agent's. If [code]false[/code] the agent calculates avoidance velocities in 2D along the xz-axis ignoring the y-axis. The 2D using agent only avoids other 2D avoidance using agent's. The 2D using agent reacts to radius avoidance obstacles. The 2D using agent reacts to vertices based avoidance obstacles. The 2D using agent only avoids other 2D using agent's. 2D using agents will ignore other 2D using agents or obstacles that are below their current position or above their current position including the agents height in 2D avoidance. </description> </method> @@ -251,6 +342,13 @@ Returns information about the current state of the NavigationServer. See [enum ProcessInfo] for a list of available states. </description> </method> + <method name="is_baking_navigation_mesh" qualifiers="const"> + <return type="bool" /> + <param index="0" name="navigation_mesh" type="NavigationMesh" /> + <description> + Returns [code]true[/code] when the provided navigation mesh is being baked on a background thread. + </description> + </method> <method name="link_create"> <return type="RID" /> <description> @@ -404,7 +502,7 @@ <description> This function immediately forces synchronization of the specified navigation [param map] [RID]. By default navigation maps are only synchronized at the end of each physics frame. This function can be used to immediately (re)calculate all the navigation meshes and region connections of the navigation map. This makes it possible to query a navigation path for a changed map immediately and in the same frame (multiple times if needed). Due to technical restrictions the current NavigationServer command queue will be flushed. This means all already queued update commands for this physics frame will be executed, even those intended for other maps, regions and agents not part of the specified map. The expensive computation of the navigation meshes and region connections of a map will only be done for the specified map. Other maps will receive the normal synchronization at the end of the physics frame. Should the specified map receive changes after the forced update it will update again as well when the other maps receive their update. - Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is untouched by this function and continues to happen for all maps and agents at the end of the physics frame. + Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is unaffected by this function and continues to happen for all maps and agents at the end of the physics frame. [b]Note:[/b] With great power comes great responsibility. This function should only be used by users that really know what they are doing and have a good reason for it. Forcing an immediate update of a navigation map requires locking the NavigationServer and flushing the entire NavigationServer command queue. Not only can this severely impact the performance of a game but it can also introduce bugs if used inappropriately without much foresight. </description> </method> @@ -470,6 +568,14 @@ Returns the edge connection margin of the map. This distance is the minimum vertex distance needed to connect two edges from different regions. </description> </method> + <method name="map_get_iteration_id" qualifiers="const"> + <return type="int" /> + <param index="0" name="map" type="RID" /> + <description> + Returns the current iteration id of the navigation map. Every time the navigation map changes and synchronizes the iteration id increases. An iteration id of 0 means the navigation map has never synchronized. + [b]Note:[/b] The iteration id will wrap back to 1 after reaching its range limit. + </description> + </method> <method name="map_get_link_connection_radius" qualifiers="const"> <return type="float" /> <param index="0" name="map" type="RID" /> @@ -484,6 +590,13 @@ Returns all navigation link [RID]s that are currently assigned to the requested navigation [param map]. </description> </method> + <method name="map_get_merge_rasterizer_cell_scale" qualifiers="const"> + <return type="float" /> + <param index="0" name="map" type="RID" /> + <description> + Returns map's internal merge rasterizer cell scale. + </description> + </method> <method name="map_get_obstacles" qualifiers="const"> <return type="RID[]" /> <param index="0" name="map" type="RID" /> @@ -502,6 +615,17 @@ Returns the navigation path to reach the destination from the origin. [param navigation_layers] is a bitmask of all region navigation layers that are allowed to be in the path. </description> </method> + <method name="map_get_random_point" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="map" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all map region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all map regions, polygons, and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random region and a random polygon are picked (faster). + </description> + </method> <method name="map_get_regions" qualifiers="const"> <return type="RID[]" /> <param index="0" name="map" type="RID" /> @@ -570,6 +694,14 @@ Set the map's link connection radius used to connect links to navigation polygons. </description> </method> + <method name="map_set_merge_rasterizer_cell_scale"> + <return type="void" /> + <param index="0" name="map" type="RID" /> + <param index="1" name="scale" type="float" /> + <description> + Set the map's internal merge rasterizer cell scale used to control merging sensitivity. + </description> + </method> <method name="map_set_up"> <return type="void" /> <param index="0" name="map" type="RID" /> @@ -599,6 +731,20 @@ Returns [code]true[/code] if the provided [param obstacle] has avoidance enabled. </description> </method> + <method name="obstacle_get_avoidance_layers" qualifiers="const"> + <return type="int" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the [code]avoidance_layers[/code] bitmask of the specified [param obstacle]. + </description> + </method> + <method name="obstacle_get_height" qualifiers="const"> + <return type="float" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the [code]height[/code] of the specified [param obstacle]. + </description> + </method> <method name="obstacle_get_map" qualifiers="const"> <return type="RID" /> <param index="0" name="obstacle" type="RID" /> @@ -613,6 +759,20 @@ Returns [code]true[/code] if the specified [param obstacle] is paused. </description> </method> + <method name="obstacle_get_position" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the position of the specified [param obstacle] in world space. + </description> + </method> + <method name="obstacle_get_radius" qualifiers="const"> + <return type="float" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the radius of the specified dynamic [param obstacle]. + </description> + </method> <method name="obstacle_get_use_3d_avoidance" qualifiers="const"> <return type="bool" /> <param index="0" name="obstacle" type="RID" /> @@ -620,6 +780,20 @@ Returns [code]true[/code] if the provided [param obstacle] uses avoidance in 3D space Vector3(x,y,z) instead of horizontal 2D Vector2(x,y) / Vector3(x,0.0,z). </description> </method> + <method name="obstacle_get_velocity" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the velocity of the specified dynamic [param obstacle]. + </description> + </method> + <method name="obstacle_get_vertices" qualifiers="const"> + <return type="PackedVector3Array" /> + <param index="0" name="obstacle" type="RID" /> + <description> + Returns the outline vertices for the specified [param obstacle]. + </description> + </method> <method name="obstacle_set_avoidance_enabled"> <return type="void" /> <param index="0" name="obstacle" type="RID" /> @@ -720,13 +894,12 @@ Queries a path in a given navigation map. Start and target position and other parameters are defined through [NavigationPathQueryParameters3D]. Updates the provided [NavigationPathQueryResult3D] result object with the path among other results requested by the query. </description> </method> - <method name="region_bake_navigation_mesh" is_deprecated="true"> + <method name="region_bake_navigation_mesh" deprecated="This method is deprecated due to core threading changes. To upgrade existing code, first create a [NavigationMeshSourceGeometryData3D] resource. Use this resource with [method parse_source_geometry_data] to parse the [SceneTree] for nodes that should contribute to the navigation mesh baking. The [SceneTree] parsing needs to happen on the main thread. After the parsing is finished use the resource with [method bake_from_source_geometry_data] to bake a navigation mesh."> <return type="void" /> <param index="0" name="navigation_mesh" type="NavigationMesh" /> <param index="1" name="root_node" type="Node" /> <description> Bakes the [param navigation_mesh] with bake source geometry collected starting from the [param root_node]. - [i]Deprecated.[/i] This function is deprecated due to core threading changes. To upgrade existing code, first create a [NavigationMeshSourceGeometryData3D] resource. Use this resource with [method parse_source_geometry_data] to parse the SceneTree for nodes that should contribute to the navigation mesh baking. The SceneTree parsing needs to happen on the main thread. After the parsing is finished use the resource with [method bake_from_source_geometry_data] to bake a navigation mesh. </description> </method> <method name="region_create"> @@ -793,6 +966,24 @@ Returns the [code]ObjectID[/code] of the object which manages this region. </description> </method> + <method name="region_get_random_point" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="region" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all region polygons and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random polygon and face is picked (faster). + </description> + </method> + <method name="region_get_transform" qualifiers="const"> + <return type="Transform3D" /> + <param index="0" name="region" type="RID" /> + <description> + Returns the global transformation of this [param region]. + </description> + </method> <method name="region_get_travel_cost" qualifiers="const"> <return type="float" /> <param index="0" name="region" type="RID" /> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 0ace4357fa..ae6cd9596c 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -11,11 +11,11 @@ This means that when adding a node to the scene tree, the following order will be used for the callbacks: [method _enter_tree] of the parent, [method _enter_tree] of the children, [method _ready] of the children and finally [method _ready] of the parent (recursively for the entire scene tree). [b]Processing:[/b] Nodes can override the "process" state, so that they receive a callback on each frame requesting them to process (do something). Normal processing (callback [method _process], toggled with [method set_process]) happens as fast as possible and is dependent on the frame rate, so the processing time [i]delta[/i] (in seconds) is passed as an argument. Physics processing (callback [method _physics_process], toggled with [method set_physics_process]) happens a fixed number of times per second (60 by default) and is useful for code related to the physics engine. Nodes can also process input events. When present, the [method _input] function will be called for each input that the program receives. In many cases, this can be overkill (unless used for simple projects), and the [method _unhandled_input] function might be preferred; it is called when the input event was not handled by anyone else (typically, GUI [Control] nodes), ensuring that the node only receives the events that were meant for it. - To keep track of the scene hierarchy (especially when instancing scenes into other scenes), an "owner" can be set for the node with the [member owner] property. This keeps track of who instantiated what. This is mostly useful when writing editors and tools, though. + To keep track of the scene hierarchy (especially when instantiating scenes into other scenes), an "owner" can be set for the node with the [member owner] property. This keeps track of who instantiated what. This is mostly useful when writing editors and tools, though. Finally, when a node is freed with [method Object.free] or [method queue_free], it will also free all its children. [b]Groups:[/b] Nodes can be added to as many groups as you want to be easy to manage, you could create groups like "enemies" or "collectables" for example, depending on your game. See [method add_to_group], [method is_in_group] and [method remove_from_group]. You can then retrieve all nodes in these groups, iterate them and even call methods on groups via the methods on [SceneTree]. [b]Networking with nodes:[/b] After connecting to a server (or making one, see [ENetMultiplayerPeer]), it is possible to use the built-in RPC (remote procedure call) system to communicate over the network. By calling [method rpc] with a method name, it will be called locally and in all connected peers (peers = clients and the server that accepts connections). To identify which node receives the RPC call, Godot will use its [NodePath] (make sure node names are the same on all peers). Also, take a look at the high-level networking tutorial and corresponding demos. - [b]Note:[/b] The [code]script[/code] property is part of the [Object] class, not [Node]. It isn't exposed like most properties but does have a setter and getter ([code]set_script()[/code] and [code]get_script()[/code]). + [b]Note:[/b] The [code]script[/code] property is part of the [Object] class, not [Node]. It isn't exposed like most properties but does have a setter and getter (see [method Object.set_script] and [method Object.get_script]). </description> <tutorials> <link title="Nodes and scenes">$DOCS_URL/getting_started/step_by_step/nodes_and_scenes.html</link> @@ -25,7 +25,7 @@ <method name="_enter_tree" qualifiers="virtual"> <return type="void" /> <description> - Called when the node enters the [SceneTree] (e.g. upon instancing, scene changing, or after calling [method add_child] in a script). If the node has children, its [method _enter_tree] callback will be called first, and then that of the children. + Called when the node enters the [SceneTree] (e.g. upon instantiating, scene changing, or after calling [method add_child] in a script). If the node has children, its [method _enter_tree] callback will be called first, and then that of the children. Corresponds to the [constant NOTIFICATION_ENTER_TREE] notification in [method Object._notification]. </description> </method> @@ -93,14 +93,14 @@ Called when the node is "ready", i.e. when both the node and its children have entered the scene tree. If the node has children, their [method _ready] callbacks get triggered first, and the parent node will receive the ready notification afterwards. Corresponds to the [constant NOTIFICATION_READY] notification in [method Object._notification]. See also the [code]@onready[/code] annotation for variables. Usually used for initialization. For even earlier initialization, [method Object._init] may be used. See also [method _enter_tree]. - [b]Note:[/b] [method _ready] may be called only once for each node. After removing a node from the scene tree and adding it again, [method _ready] will not be called a second time. This can be bypassed by requesting another call with [method request_ready], which may be called anywhere before adding the node again. + [b]Note:[/b] This method may be called only once for each node. After removing a node from the scene tree and adding it again, [method _ready] will [b]not[/b] be called a second time. This can be bypassed by requesting another call with [method request_ready], which may be called anywhere before adding the node again. </description> </method> <method name="_shortcut_input" qualifiers="virtual"> <return type="void" /> <param index="0" name="event" type="InputEvent" /> <description> - Called when an [InputEventKey] or [InputEventShortcut] hasn't been consumed by [method _input] or any GUI [Control] item. It is called before [method _unhandled_key_input] and [method _unhandled_input]. The input event propagates up through the node tree until a node consumes it. + Called when an [InputEventKey], [InputEventShortcut], or [InputEventJoypadButton] hasn't been consumed by [method _input] or any GUI [Control] item. It is called before [method _unhandled_key_input] and [method _unhandled_input]. The input event propagates up through the node tree until a node consumes it. It is only called if shortcut processing is enabled, which is done automatically if this method is overridden, and can be toggled with [method set_process_shortcut_input]. To consume the input event and stop it propagating further to other nodes, [method Viewport.set_input_as_handled] can be called. This method can be used to handle shortcuts. For generic GUI events, use [method _input] instead. Gameplay events should usually be handled with either [method _unhandled_input] or [method _unhandled_key_input]. @@ -138,8 +138,8 @@ <description> Adds a child [param node]. Nodes can have any number of children, but every child must have a unique name. Child nodes are automatically deleted when the parent node is deleted, so an entire scene can be removed by deleting its topmost node. If [param force_readable_name] is [code]true[/code], improves the readability of the added [param node]. If not named, the [param node] is renamed to its type, and if it shares [member name] with a sibling, a number is suffixed more appropriately. This operation is very slow. As such, it is recommended leaving this to [code]false[/code], which assigns a dummy name featuring [code]@[/code] in both situations. - If [param internal] is different than [constant INTERNAL_MODE_DISABLED], the child will be added as internal node. Such nodes are ignored by methods like [method get_children], unless their parameter [code]include_internal[/code] is [code]true[/code]. The intended usage is to hide the internal nodes from the user, so the user won't accidentally delete or modify them. Used by some GUI nodes, e.g. [ColorPicker]. See [enum InternalMode] for available modes. - [b]Note:[/b] If the child node already has a parent, the function will fail. Use [method remove_child] first to remove the node from its current parent. For example: + If [param internal] is different than [constant INTERNAL_MODE_DISABLED], the child will be added as internal node. These nodes are ignored by methods like [method get_children], unless their parameter [code]include_internal[/code] is [code]true[/code]. The intended usage is to hide the internal nodes from the user, so the user won't accidentally delete or modify them. Used by some GUI nodes, e.g. [ColorPicker]. See [enum InternalMode] for available modes. + [b]Note:[/b] If [param node] already has a parent, this method will fail. Use [method remove_child] first to remove [param node] from its current parent. For example: [codeblocks] [gdscript] var child_node = get_child(0) @@ -165,10 +165,10 @@ <param index="0" name="sibling" type="Node" /> <param index="1" name="force_readable_name" type="bool" default="false" /> <description> - Adds a [param sibling] node to current's node parent, at the same level as that node, right below it. + Adds a [param sibling] node to this node's parent, and moves the added sibling right below this node. If [param force_readable_name] is [code]true[/code], improves the readability of the added [param sibling]. If not named, the [param sibling] is renamed to its type, and if it shares [member name] with a sibling, a number is suffixed more appropriately. This operation is very slow. As such, it is recommended leaving this to [code]false[/code], which assigns a dummy name featuring [code]@[/code] in both situations. Use [method add_child] instead of this method if you don't need the child node to be added below a specific node in the list of children. - [b]Note:[/b] If this node is internal, the new sibling will be internal too (see [code]internal[/code] parameter in [method add_child]). + [b]Note:[/b] If this node is internal, the added sibling will be internal too (see [method add_child]'s [code]internal[/code] parameter). </description> </method> <method name="add_to_group"> @@ -176,9 +176,36 @@ <param index="0" name="group" type="StringName" /> <param index="1" name="persistent" type="bool" default="false" /> <description> - Adds the node to a group. Groups are helpers to name and organize a subset of nodes, for example "enemies" or "collectables". A node can be in any number of groups. Nodes can be assigned a group at any time, but will not be added until they are inside the scene tree (see [method is_inside_tree]). See notes in the description, and the group methods in [SceneTree]. - The [param persistent] option is used when packing node to [PackedScene] and saving to file. Non-persistent groups aren't stored. - [b]Note:[/b] For performance reasons, the order of node groups is [i]not[/i] guaranteed. The order of node groups should not be relied upon as it can vary across project runs. + Adds the node to the [param group]. Groups can be helpful to organize a subset of nodes, for example [code]"enemies"[/code] or [code]"collectables"[/code]. See notes in the description, and the group methods in [SceneTree]. + If [param persistent] is [code]true[/code], the group will be stored when saved inside a [PackedScene]. All groups created and displayed in the Node dock are persistent. + [b]Note:[/b] To improve performance, the order of group names is [i]not[/i] guaranteed and may vary between project runs. Therefore, do not rely on the group order. + [b]Note:[/b] [SceneTree]'s group methods will [i]not[/i] work on this node if not inside the tree (see [method is_inside_tree]). + </description> + </method> + <method name="atr" qualifiers="const"> + <return type="String" /> + <param index="0" name="message" type="String" /> + <param index="1" name="context" type="StringName" default="""" /> + <description> + Translates a [param message], using the translation catalogs configured in the Project Settings. Further [param context] can be specified to help with the translation. Note that most [Control] nodes automatically translate their strings, so this method is mostly useful for formatted strings or custom drawn text. + This method works the same as [method Object.tr], with the addition of respecting the [member auto_translate_mode] state. + If [method Object.can_translate_messages] is [code]false[/code], or no translation is available, this method returns the [param message] without changes. See [method Object.set_message_translation]. + For detailed examples, see [url=$DOCS_URL/tutorials/i18n/internationalizing_games.html]Internationalizing games[/url]. + </description> + </method> + <method name="atr_n" qualifiers="const"> + <return type="String" /> + <param index="0" name="message" type="String" /> + <param index="1" name="plural_message" type="StringName" /> + <param index="2" name="n" type="int" /> + <param index="3" name="context" type="StringName" default="""" /> + <description> + Translates a [param message] or [param plural_message], using the translation catalogs configured in the Project Settings. Further [param context] can be specified to help with the translation. + This method works the same as [method Object.tr_n], with the addition of respecting the [member auto_translate_mode] state. + If [method Object.can_translate_messages] is [code]false[/code], or no translation is available, this method returns [param message] or [param plural_message], without changes. See [method Object.set_message_translation]. + The [param n] is the number, or amount, of the message's subject. It is used by the translation system to fetch the correct plural form for the current language. + For detailed examples, see [url=$DOCS_URL/tutorials/i18n/localization_using_gettext.html]Localization using gettext[/url]. + [b]Note:[/b] Negative and [float] numbers may not properly apply to some countable subjects. It's recommended to handle these cases with [method atr]. </description> </method> <method name="call_deferred_thread_group" qualifiers="vararg"> @@ -198,13 +225,20 @@ <method name="can_process" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the node can process while the scene tree is paused (see [member process_mode]). Always returns [code]true[/code] if the scene tree is not paused, and [code]false[/code] if the node is not in the tree. + Returns [code]true[/code] if the node can receive processing notifications and input callbacks ([constant NOTIFICATION_PROCESS], [method _input], etc.) from the [SceneTree] and [Viewport]. The returned value depends on [member process_mode]: + - If set to [constant PROCESS_MODE_PAUSABLE], returns [code]true[/code] when the game is processing, i.e. [member SceneTree.paused] is [code]false[/code]; + - If set to [constant PROCESS_MODE_WHEN_PAUSED], returns [code]true[/code] when the game is paused, i.e. [member SceneTree.paused] is [code]true[/code]; + - If set to [constant PROCESS_MODE_ALWAYS], always returns [code]true[/code]; + - If set to [constant PROCESS_MODE_DISABLED], always returns [code]false[/code]; + - If set to [constant PROCESS_MODE_INHERIT], use the parent node's [member process_mode] to determine the result. + If the node is not inside the tree, returns [code]false[/code] no matter the value of [member process_mode]. </description> </method> <method name="create_tween"> <return type="Tween" /> <description> - Creates a new [Tween] and binds it to this node. This is equivalent of doing: + Creates a new [Tween] and binds it to this node. + This is the equivalent of doing: [codeblocks] [gdscript] get_tree().create_tween().bind_node(self) @@ -213,16 +247,16 @@ GetTree().CreateTween().BindNode(this); [/csharp] [/codeblocks] - The Tween will start automatically on the next process frame or physics frame (depending on [enum Tween.TweenProcessMode]). + The Tween will start automatically on the next process frame or physics frame (depending on [enum Tween.TweenProcessMode]). See [method Tween.bind_node] for more info on Tweens bound to nodes. + [b]Note:[/b] The method can still be used when the node is not inside [SceneTree]. It can fail in an unlikely case of using a custom [MainLoop]. </description> </method> <method name="duplicate" qualifiers="const"> <return type="Node" /> <param index="0" name="flags" type="int" default="15" /> <description> - Duplicates the node, returning a new node. - You can fine-tune the behavior using the [param flags] (see [enum DuplicateFlags]). - [b]Note:[/b] It will not work properly if the node contains a script with constructor arguments (i.e. needs to supply arguments to [method Object._init] method). In that case, the node will be duplicated without a script. + Duplicates the node, returning a new node with all of its properties, signals and groups copied from the original. The behavior can be tweaked through the [param flags] (see [enum DuplicateFlags]). + [b]Note:[/b] For nodes with a [Script] attached, if [method Object._init] has been defined with required parameters, the duplicated node will not have a [Script]. </description> </method> <method name="find_child" qualifiers="const"> @@ -231,12 +265,10 @@ <param index="1" name="recursive" type="bool" default="true" /> <param index="2" name="owned" type="bool" default="true" /> <description> - Finds the first descendant of this node whose name matches [param pattern] as in [method String.match]. Internal children are also searched over (see [code]internal[/code] parameter in [method add_child]). - [param pattern] does not match against the full path, just against individual node names. It is case-sensitive, with [code]"*"[/code] matching zero or more characters and [code]"?"[/code] matching any single character except [code]"."[/code]). - If [param recursive] is [code]true[/code], all child nodes are included, even if deeply nested. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. If [param recursive] is [code]false[/code], only this node's direct children are matched. - If [param owned] is [code]true[/code], this method only finds nodes who have an assigned [member Node.owner]. This is especially important for scenes instantiated through a script, because those scenes don't have an owner. - Returns [code]null[/code] if no matching [Node] is found. - [b]Note:[/b] As this method walks through all the descendants of the node, it is the slowest way to get a reference to another node. Whenever possible, consider using [method get_node] with unique names instead (see [member unique_name_in_owner]), or caching the node references into variable. + Finds the first descendant of this node whose [member name] matches [param pattern], returning [code]null[/code] if no match is found. The matching is done against node names, [i]not[/i] their paths, through [method String.match]. As such, it is case-sensitive, [code]"*"[/code] matches zero or more characters, and [code]"?"[/code] matches any single character. + If [param recursive] is [code]false[/code], only this node's direct children are checked. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. Internal children are also included in the search (see [code]internal[/code] parameter in [method add_child]). + If [param owned] is [code]true[/code], only descendants with a valid [member owner] node are checked. + [b]Note:[/b] This method can be very slow. Consider storing a reference to the found node in a variable. Alternatively, use [method get_node] with unique names (see [member unique_name_in_owner]). [b]Note:[/b] To find all descendant nodes matching a pattern or a class type, see [method find_children]. </description> </method> @@ -247,23 +279,20 @@ <param index="2" name="recursive" type="bool" default="true" /> <param index="3" name="owned" type="bool" default="true" /> <description> - Finds descendants of this node whose name matches [param pattern] as in [method String.match], and/or type matches [param type] as in [method Object.is_class]. Internal children are also searched over (see [code]internal[/code] parameter in [method add_child]). - [param pattern] does not match against the full path, just against individual node names. It is case-sensitive, with [code]"*"[/code] matching zero or more characters and [code]"?"[/code] matching any single character except [code]"."[/code]). - [param type] will check equality or inheritance, and is case-sensitive. [code]"Object"[/code] will match a node whose type is [code]"Node"[/code] but not the other way around. - If [param recursive] is [code]true[/code], all child nodes are included, even if deeply nested. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. If [param recursive] is [code]false[/code], only this node's direct children are matched. - If [param owned] is [code]true[/code], this method only finds nodes who have an assigned [member Node.owner]. This is especially important for scenes instantiated through a script, because those scenes don't have an owner. - Returns an empty array if no matching nodes are found. - [b]Note:[/b] As this method walks through all the descendants of the node, it is the slowest way to get references to other nodes. Whenever possible, consider caching the node references into variables. - [b]Note:[/b] If you only want to find the first descendant node that matches a pattern, see [method find_child]. + Finds all descendants of this node whose names match [param pattern], returning an empty [Array] if no match is found. The matching is done against node names, [i]not[/i] their paths, through [method String.match]. As such, it is case-sensitive, [code]"*"[/code] matches zero or more characters, and [code]"?"[/code] matches any single character. + If [param type] is not empty, only ancestors inheriting from [param type] are included (see [method Object.is_class]). + If [param recursive] is [code]false[/code], only this node's direct children are checked. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. Internal children are also included in the search (see [code]internal[/code] parameter in [method add_child]). + If [param owned] is [code]true[/code], only descendants with a valid [member owner] node are checked. + [b]Note:[/b] This method can be very slow. Consider storing references to the found nodes in a variable. + [b]Note:[/b] To find a single descendant node matching a pattern, see [method find_child]. </description> </method> <method name="find_parent" qualifiers="const"> <return type="Node" /> <param index="0" name="pattern" type="String" /> <description> - Finds the first parent of the current node whose name matches [param pattern] as in [method String.match]. - [param pattern] does not match against the full path, just against individual node names. It is case-sensitive, with [code]"*"[/code] matching zero or more characters and [code]"?"[/code] matching any single character except [code]"."[/code]). - [b]Note:[/b] As this method walks upwards in the scene tree, it can be slow in large, deeply nested scene trees. Whenever possible, consider using [method get_node] with unique names instead (see [member unique_name_in_owner]), or caching the node references into variable. + Finds the first ancestor of this node whose [member name] matches [param pattern], returning [code]null[/code] if no match is found. The matching is done through [method String.match]. As such, it is case-sensitive, [code]"*"[/code] matches zero or more characters, and [code]"?"[/code] matches any single character. See also [method find_child] and [method find_children]. + [b]Note:[/b] As this method walks upwards in the scene tree, it can be slow in large, deeply nested nodes. Consider storing a reference to the found node in a variable. Alternatively, use [method get_node] with unique names (see [member unique_name_in_owner]). </description> </method> <method name="get_child" qualifiers="const"> @@ -271,44 +300,52 @@ <param index="0" name="idx" type="int" /> <param index="1" name="include_internal" type="bool" default="false" /> <description> - Returns a child node by its index (see [method get_child_count]). This method is often used for iterating all children of a node. - Negative indices access the children from the last one. - If [param include_internal] is [code]false[/code], internal children are skipped (see [code]internal[/code] parameter in [method add_child]). - To access a child node via its name, use [method get_node]. + Fetches a child node by its index. Each child node has an index relative its siblings (see [method get_index]). The first child is at index 0. Negative values can also be used to start from the end of the list. This method can be used in combination with [method get_child_count] to iterate over this node's children. If no child exists at the given index, this method returns [code]null[/code] and an error is generated. + If [param include_internal] is [code]false[/code], internal children are ignored (see [method add_child]'s [code]internal[/code] parameter). + [codeblock] + # Assuming the following are children of this node, in order: + # First, Middle, Last. + + var a = get_child(0).name # a is "First" + var b = get_child(1).name # b is "Middle" + var b = get_child(2).name # b is "Last" + var c = get_child(-1).name # c is "Last" + [/codeblock] + [b]Note:[/b] To fetch a node by [NodePath], use [method get_node]. </description> </method> <method name="get_child_count" qualifiers="const"> <return type="int" /> <param index="0" name="include_internal" type="bool" default="false" /> <description> - Returns the number of child nodes. - If [param include_internal] is [code]false[/code], internal children aren't counted (see [code]internal[/code] parameter in [method add_child]). + Returns the number of children of this node. + If [param include_internal] is [code]false[/code], internal children are not counted (see [method add_child]'s [code]internal[/code] parameter). </description> </method> <method name="get_children" qualifiers="const"> <return type="Node[]" /> <param index="0" name="include_internal" type="bool" default="false" /> <description> - Returns an array of references to node's children. - If [param include_internal] is [code]false[/code], the returned array won't include internal children (see [code]internal[/code] parameter in [method add_child]). + Returns all children of this node inside an [Array]. + If [param include_internal] is [code]false[/code], excludes internal children from the returned array (see [method add_child]'s [code]internal[/code] parameter). </description> </method> <method name="get_groups" qualifiers="const"> <return type="StringName[]" /> <description> - Returns an array listing the groups that the node is a member of. - [b]Note:[/b] For performance reasons, the order of node groups is [i]not[/i] guaranteed. The order of node groups should not be relied upon as it can vary across project runs. - [b]Note:[/b] The engine uses some group names internally (all starting with an underscore). To avoid conflicts with internal groups, do not add custom groups whose name starts with an underscore. To exclude internal groups while looping over [method get_groups], use the following snippet: + Returns an [Array] of group names that the node has been added to. + [b]Note:[/b] To improve performance, the order of group names is [i]not[/i] guaranteed and may vary between project runs. Therefore, do not rely on the group order. + [b]Note:[/b] This method may also return some group names starting with an underscore ([code]_[/code]). These are internally used by the engine. To avoid conflicts, do not use custom groups starting with underscores. To exclude internal groups, see the following code snippet: [codeblocks] [gdscript] - # Stores the node's non-internal groups only (as an array of Strings). + # Stores the node's non-internal groups only (as an array of StringNames). var non_internal_groups = [] for group in get_groups(): - if not group.begins_with("_"): + if not str(group).begins_with("_"): non_internal_groups.push_back(group) [/gdscript] [csharp] - // Stores the node's non-internal groups only (as a List of strings). + // Stores the node's non-internal groups only (as a List of StringNames). List<string> nonInternalGroups = new List<string>(); foreach (string group in GetGroups()) { @@ -323,8 +360,8 @@ <return type="int" /> <param index="0" name="include_internal" type="bool" default="false" /> <description> - Returns the node's order in the scene tree branch. For example, if called on the first child node the position is [code]0[/code]. - If [param include_internal] is [code]false[/code], the index won't take internal children into account, i.e. first non-internal child will have index of 0 (see [code]internal[/code] parameter in [method add_child]). + Returns this node's order among its siblings. The first node's index is [code]0[/code]. See also [method get_child]. + If [param include_internal] is [code]false[/code], returns the index ignoring internal children. The first, non-internal child will have an index of [code]0[/code] (see [method add_child]'s [code]internal[/code] parameter). </description> </method> <method name="get_last_exclusive_window" qualifiers="const"> @@ -343,20 +380,22 @@ <return type="Node" /> <param index="0" name="path" type="NodePath" /> <description> - Fetches a node. The [NodePath] can be either a relative path (from the current node) or an absolute path (in the scene tree) to a node. If the path does not exist, [code]null[/code] is returned and an error is logged. Attempts to access methods on the return value will result in an "Attempt to call <method> on a null instance." error. - [b]Note:[/b] Fetching absolute paths only works when the node is inside the scene tree (see [method is_inside_tree]). - [b]Example:[/b] Assume your current node is Character and the following tree: + Fetches a node. The [NodePath] can either be a relative path (from this node), or an absolute path (from the [member SceneTree.root]) to a node. If [param path] does not point to a valid node, generates an error and returns [code]null[/code]. Attempts to access methods on the return value will result in an [i]"Attempt to call <method> on a null instance."[/i] error. + [b]Note:[/b] Fetching by absolute path only works when the node is inside the scene tree (see [method is_inside_tree]). + [b]Example:[/b] Assume this method is called from the Character node, inside the following tree: [codeblock] - /root - /root/Character - /root/Character/Sword - /root/Character/Backpack/Dagger - /root/MyGame - /root/Swamp/Alligator - /root/Swamp/Mosquito - /root/Swamp/Goblin + ┖╴root + ┠╴Character (you are here!) + ┃ ┠╴Sword + ┃ ┖╴Backpack + ┃ ┖╴Dagger + ┠╴MyGame + ┖╴Swamp + ┠╴Alligator + ┠╴Mosquito + ┖╴Goblin [/codeblock] - Possible paths are: + The following calls will return a valid node: [codeblocks] [gdscript] get_node("Sword") @@ -377,19 +416,43 @@ <return type="Array" /> <param index="0" name="path" type="NodePath" /> <description> - Fetches a node and one of its resources as specified by the [NodePath]'s subname (e.g. [code]Area2D/CollisionShape2D:shape[/code]). If several nested resources are specified in the [NodePath], the last one will be fetched. - The return value is an array of size 3: the first index points to the [Node] (or [code]null[/code] if not found), the second index points to the [Resource] (or [code]null[/code] if not found), and the third index is the remaining [NodePath], if any. - For example, assuming that [code]Area2D/CollisionShape2D[/code] is a valid node and that its [code]shape[/code] property has been assigned a [RectangleShape2D] resource, one could have this kind of output: + Fetches a node and its most nested resource as specified by the [NodePath]'s subname. Returns an [Array] of size [code]3[/code] where: + - Element [code]0[/code] is the [Node], or [code]null[/code] if not found; + - Element [code]1[/code] is the subname's last nested [Resource], or [code]null[/code] if not found; + - Element [code]2[/code] is the remaining [NodePath], referring to an existing, non-[Resource] property (see [method Object.get_indexed]). + [b]Example:[/b] Assume that the child's [member Sprite2D.texture] has been assigned a [AtlasTexture]: [codeblocks] [gdscript] - print(get_node_and_resource("Area2D/CollisionShape2D")) # [[CollisionShape2D:1161], Null, ] - print(get_node_and_resource("Area2D/CollisionShape2D:shape")) # [[CollisionShape2D:1161], [RectangleShape2D:1156], ] - print(get_node_and_resource("Area2D/CollisionShape2D:shape:extents")) # [[CollisionShape2D:1161], [RectangleShape2D:1156], :extents] + var a = get_node_and_resource("Area2D/Sprite2D") + print(a[0].name) # Prints Sprite2D + print(a[1]) # Prints <null> + print(a[2]) # Prints ^"" + + var b = get_node_and_resource("Area2D/Sprite2D:texture:atlas") + print(b[0].name) # Prints Sprite2D + print(b[1].get_class()) # Prints AtlasTexture + print(b[2]) # Prints ^"" + + var c = get_node_and_resource("Area2D/Sprite2D:texture:atlas:region") + print(c[0].name) # Prints Sprite2D + print(c[1].get_class()) # Prints AtlasTexture + print(c[2]) # Prints ^":region" [/gdscript] [csharp] - GD.Print(GetNodeAndResource("Area2D/CollisionShape2D")); // [[CollisionShape2D:1161], Null, ] - GD.Print(GetNodeAndResource("Area2D/CollisionShape2D:shape")); // [[CollisionShape2D:1161], [RectangleShape2D:1156], ] - GD.Print(GetNodeAndResource("Area2D/CollisionShape2D:shape:extents")); // [[CollisionShape2D:1161], [RectangleShape2D:1156], :extents] + var a = GetNodeAndResource(NodePath("Area2D/Sprite2D")); + GD.Print(a[0].Name); // Prints Sprite2D + GD.Print(a[1]); // Prints <null> + GD.Print(a[2]); // Prints ^" + + var b = GetNodeAndResource(NodePath("Area2D/Sprite2D:texture:atlas")); + GD.Print(b[0].name); // Prints Sprite2D + GD.Print(b[1].get_class()); // Prints AtlasTexture + GD.Print(b[2]); // Prints ^"" + + var c = GetNodeAndResource(NodePath("Area2D/Sprite2D:texture:atlas:region")); + GD.Print(c[0].name); // Prints Sprite2D + GD.Print(c[1].get_class()); // Prints AtlasTexture + GD.Print(c[2]); // Prints ^":region" [/csharp] [/codeblocks] </description> @@ -398,19 +461,19 @@ <return type="Node" /> <param index="0" name="path" type="NodePath" /> <description> - Similar to [method get_node], but does not log an error if [param path] does not point to a valid [Node]. + Fetches a node by [NodePath]. Similar to [method get_node], but does not generate an error if [param path] does not point to a valid node. </description> </method> <method name="get_parent" qualifiers="const"> <return type="Node" /> <description> - Returns the parent node of the current node, or [code]null[/code] if the node lacks a parent. + Returns this node's parent node, or [code]null[/code] if the node doesn't have a parent. </description> </method> <method name="get_path" qualifiers="const"> <return type="NodePath" /> <description> - Returns the absolute path of the current node. This only works if the current node is inside the scene tree (see [method is_inside_tree]). + Returns the node's absolute path, relative to the [member SceneTree.root]. If the node is not inside the scene tree, this method fails and returns an empty [NodePath]. </description> </method> <method name="get_path_to" qualifiers="const"> @@ -418,33 +481,33 @@ <param index="0" name="node" type="Node" /> <param index="1" name="use_unique_path" type="bool" default="false" /> <description> - Returns the relative [NodePath] from this node to the specified [param node]. Both nodes must be in the same scene or the function will fail. - If [param use_unique_path] is [code]true[/code], returns the shortest path considering unique node. - [b]Note:[/b] If you get a relative path which starts from a unique node, the path may be longer than a normal relative path due to the addition of the unique node's name. + Returns the relative [NodePath] from this node to the specified [param node]. Both nodes must be in the same [SceneTree] or scene hierarchy, otherwise this method fails and returns an empty [NodePath]. + If [param use_unique_path] is [code]true[/code], returns the shortest path accounting for this node's unique name (see [member unique_name_in_owner]). + [b]Note:[/b] If you get a relative path which starts from a unique node, the path may be longer than a normal relative path, due to the addition of the unique node's name. </description> </method> <method name="get_physics_process_delta_time" qualifiers="const"> <return type="float" /> <description> - Returns the time elapsed (in seconds) since the last physics-bound frame (see [method _physics_process]). This is always a constant value in physics processing unless the frames per second is changed via [member Engine.physics_ticks_per_second]. + Returns the time elapsed (in seconds) since the last physics callback. This value is identical to [method _physics_process]'s [code]delta[/code] parameter, and is often consistent at run-time, unless [member Engine.physics_ticks_per_second] is changed. See also [constant NOTIFICATION_PHYSICS_PROCESS]. </description> </method> <method name="get_process_delta_time" qualifiers="const"> <return type="float" /> <description> - Returns the time elapsed (in seconds) since the last process callback. This value may vary from frame to frame. + Returns the time elapsed (in seconds) since the last process callback. This value is identical to [method _process]'s [code]delta[/code] parameter, and may vary from frame to frame. See also [constant NOTIFICATION_PROCESS]. </description> </method> <method name="get_scene_instance_load_placeholder" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this is an instance load placeholder. See [InstancePlaceholder]. + Returns [code]true[/code] if this node is an instance load placeholder. See [InstancePlaceholder] and [method set_scene_instance_load_placeholder]. </description> </method> <method name="get_tree" qualifiers="const"> <return type="SceneTree" /> <description> - Returns the [SceneTree] that contains this node. Returns [code]null[/code] and prints an error if this node is not inside the scene tree. See also [method is_inside_tree]. + Returns the [SceneTree] that contains this node. If this node is not inside the tree, generates an error and returns [code]null[/code]. See also [method is_inside_tree]. </description> </method> <method name="get_tree_string"> @@ -480,7 +543,7 @@ <method name="get_viewport" qualifiers="const"> <return type="Viewport" /> <description> - Returns the node's [Viewport]. + Returns the node's closest [Viewport] ancestor, if the node is inside the tree. Otherwise, returns [code]null[/code]. </description> </method> <method name="get_window" qualifiers="const"> @@ -493,54 +556,54 @@ <return type="bool" /> <param index="0" name="path" type="NodePath" /> <description> - Returns [code]true[/code] if the node that the [NodePath] points to exists. + Returns [code]true[/code] if the [param path] points to a valid node. See also [method get_node]. </description> </method> <method name="has_node_and_resource" qualifiers="const"> <return type="bool" /> <param index="0" name="path" type="NodePath" /> <description> - Returns [code]true[/code] if the [NodePath] points to a valid node and its subname points to a valid resource, e.g. [code]Area2D/CollisionShape2D:shape[/code]. Properties with a non-[Resource] type (e.g. nodes or primitive math types) are not considered resources. + Returns [code]true[/code] if [param path] points to a valid node and its subnames point to a valid [Resource], e.g. [code]Area2D/CollisionShape2D:shape[/code]. Properties that are not [Resource] types (such as nodes or other [Variant] types) are not considered. See also [method get_node_and_resource]. </description> </method> <method name="is_ancestor_of" qualifiers="const"> <return type="bool" /> <param index="0" name="node" type="Node" /> <description> - Returns [code]true[/code] if the given node is a direct or indirect child of the current node. + Returns [code]true[/code] if the given [param node] is a direct or indirect child of this node. </description> </method> <method name="is_displayed_folded" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the node is folded (collapsed) in the Scene dock. This method is only intended for use with editor tooling. + Returns [code]true[/code] if the node is folded (collapsed) in the Scene dock. This method is intended to be used in editor plugins and tools. See also [method set_display_folded]. </description> </method> <method name="is_editable_instance" qualifiers="const"> <return type="bool" /> <param index="0" name="node" type="Node" /> <description> - Returns [code]true[/code] if [param node] has editable children enabled relative to this node. This method is only intended for use with editor tooling. + Returns [code]true[/code] if [param node] has editable children enabled relative to this node. This method is intended to be used in editor plugins and tools. See also [method set_editable_instance]. </description> </method> <method name="is_greater_than" qualifiers="const"> <return type="bool" /> <param index="0" name="node" type="Node" /> <description> - Returns [code]true[/code] if the given node occurs later in the scene hierarchy than the current node. + Returns [code]true[/code] if the given [param node] occurs later in the scene hierarchy than this node. A node occurring later is usually processed last. </description> </method> <method name="is_in_group" qualifiers="const"> <return type="bool" /> <param index="0" name="group" type="StringName" /> <description> - Returns [code]true[/code] if this node is in the specified group. See notes in the description, and the group methods in [SceneTree]. + Returns [code]true[/code] if this node has been added to the given [param group]. See [method add_to_group] and [method remove_from_group]. See also notes in the description, and the [SceneTree]'s group methods. </description> </method> <method name="is_inside_tree" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this node is currently inside a [SceneTree]. + Returns [code]true[/code] if this node is currently inside a [SceneTree]. See also [method get_tree]. </description> </method> <method name="is_multiplayer_authority" qualifiers="const"> @@ -556,6 +619,21 @@ [method request_ready] resets it back to [code]false[/code]. </description> </method> + <method name="is_physics_interpolated" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if physics interpolation is enabled for this node (see [member physics_interpolation_mode]). + [b]Note:[/b] Interpolation will only be active if both the flag is set [b]and[/b] physics interpolation is enabled within the [SceneTree]. This can be tested using [method is_physics_interpolated_and_enabled]. + </description> + </method> + <method name="is_physics_interpolated_and_enabled" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if physics interpolation is enabled (see [member physics_interpolation_mode]) [b]and[/b] enabled in the [SceneTree]. + This is a convenience version of [method is_physics_interpolated] that also checks whether physics interpolation is enabled globally. + See [member SceneTree.physics_interpolation] and [member ProjectSettings.physics/common/physics_interpolation]. + </description> + </method> <method name="is_physics_processing" qualifiers="const"> <return type="bool" /> <description> @@ -609,8 +687,8 @@ <param index="0" name="child_node" type="Node" /> <param index="1" name="to_index" type="int" /> <description> - Moves a child node to a different index (order) among the other children. Since calls, signals, etc. are performed by tree order, changing the order of children nodes may be useful. If [param to_index] is negative, the index will be counted from the end. - [b]Note:[/b] Internal children can only be moved within their expected "internal range" (see [code]internal[/code] parameter in [method add_child]). + Moves [param child_node] to the given index. A node's index is the order among its siblings. If [param to_index] is negative, the index is counted from the end of the list. See also [method get_child] and [method get_index]. + [b]Note:[/b] The processing order of several engine callbacks ([method _ready], [method _process], etc.) and notifications sent through [method propagate_notification] is affected by tree order. [CanvasItem] nodes are also rendered in tree order. See also [member process_priority]. </description> </method> <method name="notify_deferred_thread_group"> @@ -630,29 +708,29 @@ <method name="print_orphan_nodes" qualifiers="static"> <return type="void" /> <description> - Prints all orphan nodes (nodes outside the [SceneTree]). Used for debugging. - [b]Note:[/b] [method print_orphan_nodes] only works in debug builds. When called in a project exported in release mode, [method print_orphan_nodes] will not print anything. + Prints all orphan nodes (nodes outside the [SceneTree]). Useful for debugging. + [b]Note:[/b] This method only works in debug builds. Does nothing in a project exported in release mode. </description> </method> <method name="print_tree"> <return type="void" /> <description> - Prints the tree to stdout. Used mainly for debugging purposes. This version displays the path relative to the current node, and is good for copy/pasting into the [method get_node] function. + Prints the node and its children to the console, recursively. The node does not have to be inside the tree. This method outputs [NodePath]s relative to this node, and is good for copy/pasting into [method get_node]. See also [method print_tree_pretty]. [b]Example output:[/b] [codeblock] - TheGame - TheGame/Menu - TheGame/Menu/Label - TheGame/Menu/Camera2D - TheGame/SplashScreen - TheGame/SplashScreen/Camera2D + . + Menu + Menu/Label + Menu/Camera2D + SplashScreen + SplashScreen/Camera2D [/codeblock] </description> </method> <method name="print_tree_pretty"> <return type="void" /> <description> - Similar to [method print_tree], this prints the tree to stdout. This version displays a more graphical representation similar to what is displayed in the Scene Dock. It is useful for inspecting larger trees. + Prints the node and its children to the console, recursively. The node does not have to be inside the tree. Similar to [method print_tree], but the graphical representation looks like what is displayed in the editor's Scene dock. It is useful for inspecting larger trees. [b]Example output:[/b] [codeblock] ┖╴TheGame @@ -670,37 +748,38 @@ <param index="1" name="args" type="Array" default="[]" /> <param index="2" name="parent_first" type="bool" default="false" /> <description> - Calls the given method (if present) with the arguments given in [param args] on this node and recursively on all its children. If the [param parent_first] argument is [code]true[/code], the method will be called on the current node first, then on all its children. If [param parent_first] is [code]false[/code], the children will be called first. + Calls the given [param method] name, passing [param args] as arguments, on this node and all of its children, recursively. + If [param parent_first] is [code]true[/code], the method is called on this node first, then on all of its children. If [code]false[/code], the children's methods are called first. </description> </method> <method name="propagate_notification"> <return type="void" /> <param index="0" name="what" type="int" /> <description> - Notifies the current node and all its children recursively by calling [method Object.notification] on all of them. + Calls [method Object.notification] with [param what] on this node and all of its children, recursively. </description> </method> - <method name="queue_free"> + <method name="queue_free" keywords="delete, remove, kill, die"> <return type="void" /> <description> - Queues a node for deletion at the end of the current frame. When deleted, all of its child nodes will be deleted as well, and all references to the node and its children will become invalid, see [method Object.free]. - It is safe to call [method queue_free] multiple times per frame on a node, and to [method Object.free] a node that is currently queued for deletion. Use [method Object.is_queued_for_deletion] to check whether a node will be deleted at the end of the frame. - The node will only be freed after all other deferred calls are finished, so using [method queue_free] is not always the same as calling [method Object.free] through [method Object.call_deferred]. + Queues this node to be deleted at the end of the current frame. When deleted, all of its children are deleted as well, and all references to the node and its children become invalid. + Unlike with [method Object.free], the node is not deleted instantly, and it can still be accessed before deletion. It is also safe to call [method queue_free] multiple times. Use [method Object.is_queued_for_deletion] to check if the node will be deleted at the end of the frame. + [b]Note:[/b] The node will only be freed after all other deferred calls are finished. Using this method is not always the same as calling [method Object.free] through [method Object.call_deferred]. </description> </method> <method name="remove_child"> <return type="void" /> <param index="0" name="node" type="Node" /> <description> - Removes a child node. The node is NOT deleted and must be deleted manually. - [b]Note:[/b] This function may set the [member owner] of the removed Node (or its descendants) to be [code]null[/code], if that [member owner] is no longer a parent or ancestor. + Removes a child [param node]. The [param node], along with its children, are [b]not[/b] deleted. To delete a node, see [method queue_free]. + [b]Note:[/b] When this node is inside the tree, this method sets the [member owner] of the removed [param node] (or its descendants) to [code]null[/code], if their [member owner] is no longer an ancestor (see [method is_ancestor_of]). </description> </method> <method name="remove_from_group"> <return type="void" /> <param index="0" name="group" type="StringName" /> <description> - Removes a node from the [param group]. Does nothing if the node is not in the [param group]. See notes in the description, and the group methods in [SceneTree]. + Removes the node from the given [param group]. Does nothing if the node is not in the [param group]. See also notes in the description, and the [SceneTree]'s group methods. </description> </method> <method name="reparent"> @@ -708,7 +787,7 @@ <param index="0" name="new_parent" type="Node" /> <param index="1" name="keep_global_transform" type="bool" default="true" /> <description> - Changes the parent of this [Node] to the [param new_parent]. The node needs to already have a parent. + Changes the parent of this [Node] to the [param new_parent]. The node needs to already have a parent. The node's [member owner] is preserved if its owner is still reachable from the new location (i.e., the node is still a descendant of the new parent after the operation). If [param keep_global_transform] is [code]true[/code], the node's global transform will be preserved if supported. [Node2D], [Node3D] and [Control] support this argument (but [Control] keeps only position). </description> </method> @@ -716,25 +795,36 @@ <return type="void" /> <param index="0" name="node" type="Node" /> <param index="1" name="keep_groups" type="bool" default="false" /> + <param index="2" name="keep_children" type="bool" default="true" /> <description> - Replaces a node in a scene by the given one. Subscriptions that pass through this node will be lost. - If [param keep_groups] is [code]true[/code], the [param node] is added to the same groups that the replaced node is in. - [b]Note:[/b] The given node will become the new parent of any child nodes that the replaced node had. - [b]Note:[/b] The replaced node is not automatically freed, so you either need to keep it in a variable for later use or free it using [method Object.free]. + Replaces this node by the given [param node]. If [param keep_children] is [code]true[/code] all children of this node are moved to [param node]. + If [param keep_groups] is [code]true[/code], the [param node] is added to the same groups that the replaced node is in (see [method add_to_group]). + [b]Warning:[/b] The replaced node is removed from the tree, but it is [b]not[/b] deleted. To prevent memory leaks, store a reference to the node in a variable, or use [method Object.free]. </description> </method> <method name="request_ready"> <return type="void" /> <description> - Requests that [method _ready] be called again. Note that the method won't be called immediately, but is scheduled for when the node is added to the scene tree again. [method _ready] is called only for the node which requested it, which means that you need to request ready for each child if you want them to call [method _ready] too (in which case, [method _ready] will be called in the same order as it would normally). + Requests [method _ready] to be called again the next time the node enters the tree. Does [b]not[/b] immediately call [method _ready]. + [b]Note:[/b] This method only affects the current node. If the node's children also need to request ready, this method needs to be called for each one of them. When the node and its children enter the tree again, the order of [method _ready] callbacks will be the same as normal. + </description> + </method> + <method name="reset_physics_interpolation"> + <return type="void" /> + <description> + When physics interpolation is active, moving a node to a radically different transform (such as placement within a level) can result in a visible glitch as the object is rendered moving from the old to new position over the physics tick. + That glitch can be prevented by calling this method, which temporarily disables interpolation until the physics tick is complete. + The notification [constant NOTIFICATION_RESET_PHYSICS_INTERPOLATION] will be received by the node and all children recursively. + [b]Note:[/b] This function should be called [b]after[/b] moving the node, rather than before. </description> </method> <method name="rpc" qualifiers="vararg"> <return type="int" enum="Error" /> <param index="0" name="method" type="StringName" /> <description> - Sends a remote procedure call request for the given [param method] to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same [NodePath], including the exact same node name. Behavior depends on the RPC configuration for the given method, see [method rpc_config] and [annotation @GDScript.@rpc]. Methods are not exposed to RPCs by default. Returns [code]null[/code]. - [b]Note:[/b] You can only safely use RPCs on clients after you received the [code]connected_to_server[/code] signal from the [MultiplayerAPI]. You also need to keep track of the connection state, either by the [MultiplayerAPI] signals like [code]server_disconnected[/code] or by checking [code]get_multiplayer().peer.get_connection_status() == CONNECTION_CONNECTED[/code]. + Sends a remote procedure call request for the given [param method] to peers on the network (and locally), sending additional arguments to the method called by the RPC. The call request will only be received by nodes with the same [NodePath], including the exact same [member name]. Behavior depends on the RPC configuration for the given [param method] (see [method rpc_config] and [annotation @GDScript.@rpc]). By default, methods are not exposed to RPCs. + May return [constant OK] if the call is successful, [constant ERR_INVALID_PARAMETER] if the arguments passed in the [param method] do not match, [constant ERR_UNCONFIGURED] if the node's [member multiplayer] cannot be fetched (such as when the node is not inside the tree), [constant ERR_CONNECTION_ERROR] if [member multiplayer]'s connection is not available. + [b]Note:[/b] You can only safely use RPCs on clients after you received the [signal MultiplayerAPI.connected_to_server] signal from the [MultiplayerAPI]. You also need to keep track of the connection state, either by the [MultiplayerAPI] signals like [signal MultiplayerAPI.server_disconnected] or by checking ([code]get_multiplayer().peer.get_connection_status() == CONNECTION_CONNECTED[/code]). </description> </method> <method name="rpc_config"> @@ -742,16 +832,12 @@ <param index="0" name="method" type="StringName" /> <param index="1" name="config" type="Variant" /> <description> - Changes the RPC mode for the given [param method] with the given [param config] which should be [code]null[/code] (to disable) or a [Dictionary] in the form: - [codeblock] - { - rpc_mode = MultiplayerAPI.RPCMode, - transfer_mode = MultiplayerPeer.TransferMode, - call_local = false, - channel = 0, - } - [/codeblock] - See [enum MultiplayerAPI.RPCMode] and [enum MultiplayerPeer.TransferMode]. An alternative is annotating methods and properties with the corresponding [annotation @GDScript.@rpc] annotation ([code]@rpc("any_peer")[/code], [code]@rpc("authority")[/code]). By default, methods are not exposed to networking (and RPCs). + Changes the RPC configuration for the given [param method]. [param config] should either be [code]null[/code] to disable the feature (as by default), or a [Dictionary] containing the following entries: + - [code]rpc_mode[/code]: see [enum MultiplayerAPI.RPCMode]; + - [code]transfer_mode[/code]: see [enum MultiplayerPeer.TransferMode]; + - [code]call_local[/code]: if [code]true[/code], the method will also be called locally; + - [code]channel[/code]: an [int] representing the channel to send the RPC on. + [b]Note:[/b] In GDScript, this method corresponds to the [annotation @GDScript.@rpc] annotation, with various parameters passed ([code]@rpc(any)[/code], [code]@rpc(authority)[/code]...). See also the [url=$DOCS_URL/tutorials/networking/high_level_multiplayer.html]high-level multiplayer[/url] tutorial. </description> </method> <method name="rpc_id" qualifiers="vararg"> @@ -759,7 +845,8 @@ <param index="0" name="peer_id" type="int" /> <param index="1" name="method" type="StringName" /> <description> - Sends a [method rpc] to a specific peer identified by [param peer_id] (see [method MultiplayerPeer.set_target_peer]). Returns [code]null[/code]. + Sends a [method rpc] to a specific peer identified by [param peer_id] (see [method MultiplayerPeer.set_target_peer]). + May return [constant OK] if the call is successful, [constant ERR_INVALID_PARAMETER] if the arguments passed in the [param method] do not match, [constant ERR_UNCONFIGURED] if the node's [member multiplayer] cannot be fetched (such as when the node is not inside the tree), [constant ERR_CONNECTION_ERROR] if [member multiplayer]'s connection is not available. </description> </method> <method name="set_deferred_thread_group"> @@ -774,7 +861,7 @@ <return type="void" /> <param index="0" name="fold" type="bool" /> <description> - Sets the folded state of the node in the Scene dock. This method is only intended for use with editor tooling. + If set to [code]true[/code], the node appears folded in the Scene dock. As a result, all of its children are hidden. This method is intended to be used in editor plugins and tools, but it also works in release builds. See also [method is_displayed_folded]. </description> </method> <method name="set_editable_instance"> @@ -782,7 +869,7 @@ <param index="0" name="node" type="Node" /> <param index="1" name="is_editable" type="bool" /> <description> - Sets the editable children state of [param node] relative to this node. This method is only intended for use with editor tooling. + Set to [code]true[/code] to allow all nodes owned by [param node] to be available, and editable, in the Scene dock, even if their [member owner] is not the scene root. This method is intended to be used in editor plugins and tools, but it also works in release builds. See also [method is_editable_instance]. </description> </method> <method name="set_multiplayer_authority"> @@ -790,73 +877,81 @@ <param index="0" name="id" type="int" /> <param index="1" name="recursive" type="bool" default="true" /> <description> - Sets the node's multiplayer authority to the peer with the given peer ID. The multiplayer authority is the peer that has authority over the node on the network. Useful in conjunction with [method rpc_config] and the [MultiplayerAPI]. Defaults to peer ID 1 (the server). If [param recursive], the given peer is recursively set as the authority for all children of this node. - [b]Warning:[/b] This does [b]not[/b] automatically replicate the new authority to other peers. It is developer's responsibility to do so. You can propagate the information about the new authority using [member MultiplayerSpawner.spawn_function], an RPC, or using a [MultiplayerSynchronizer]. Also, the parent's authority does [b]not[/b] propagate to newly added children. + Sets the node's multiplayer authority to the peer with the given peer [param id]. The multiplayer authority is the peer that has authority over the node on the network. Defaults to peer ID 1 (the server). Useful in conjunction with [method rpc_config] and the [MultiplayerAPI]. + If [param recursive] is [code]true[/code], the given peer is recursively set as the authority for all children of this node. + [b]Warning:[/b] This does [b]not[/b] automatically replicate the new authority to other peers. It is the developer's responsibility to do so. You may replicate the new authority's information using [member MultiplayerSpawner.spawn_function], an RPC, or a [MultiplayerSynchronizer]. Furthermore, the parent's authority does [b]not[/b] propagate to newly added children. </description> </method> <method name="set_physics_process"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables or disables physics (i.e. fixed framerate) processing. When a node is being processed, it will receive a [constant NOTIFICATION_PHYSICS_PROCESS] at a fixed (usually 60 FPS, see [member Engine.physics_ticks_per_second] to change) interval (and the [method _physics_process] callback will be called if exists). Enabled automatically if [method _physics_process] is overridden. Any calls to this before [method _ready] will be ignored. + If set to [code]true[/code], enables physics (fixed framerate) processing. When a node is being processed, it will receive a [constant NOTIFICATION_PHYSICS_PROCESS] at a fixed (usually 60 FPS, see [member Engine.physics_ticks_per_second] to change) interval (and the [method _physics_process] callback will be called if it exists). + [b]Note:[/b] If [method _physics_process] is overridden, this will be automatically enabled before [method _ready] is called. </description> </method> <method name="set_physics_process_internal"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables or disables internal physics for this node. Internal physics processing happens in isolation from the normal [method _physics_process] calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or physics processing is disabled for scripting ([method set_physics_process]). Only useful for advanced uses to manipulate built-in nodes' behavior. - [b]Warning:[/b] Built-in Nodes rely on the internal processing for their own logic, so changing this value from your code may lead to unexpected behavior. Script access to this internal logic is provided for specific advanced uses, but is unsafe and not supported. + If set to [code]true[/code], enables internal physics for this node. Internal physics processing happens in isolation from the normal [method _physics_process] calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or physics processing is disabled for scripting ([method set_physics_process]). + [b]Warning:[/b] Built-in nodes rely on internal processing for their internal logic. Disabling it is unsafe and may lead to unexpected behavior. Use this method if you know what you are doing. </description> </method> <method name="set_process"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables or disables processing. When a node is being processed, it will receive a [constant NOTIFICATION_PROCESS] on every drawn frame (and the [method _process] callback will be called if exists). Enabled automatically if [method _process] is overridden. Any calls to this before [method _ready] will be ignored. + If set to [code]true[/code], enables processing. When a node is being processed, it will receive a [constant NOTIFICATION_PROCESS] on every drawn frame (and the [method _process] callback will be called if it exists). + [b]Note:[/b] If [method _process] is overridden, this will be automatically enabled before [method _ready] is called. + [b]Note:[/b] This method only affects the [method _process] callback, i.e. it has no effect on other callbacks like [method _physics_process]. If you want to disable all processing for the node, set [member process_mode] to [constant PROCESS_MODE_DISABLED]. </description> </method> <method name="set_process_input"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables or disables input processing. This is not required for GUI controls! Enabled automatically if [method _input] is overridden. Any calls to this before [method _ready] will be ignored. + If set to [code]true[/code], enables input processing. + [b]Note:[/b] If [method _input] is overridden, this will be automatically enabled before [method _ready] is called. Input processing is also already enabled for GUI controls, such as [Button] and [TextEdit]. </description> </method> <method name="set_process_internal"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables or disabled internal processing for this node. Internal processing happens in isolation from the normal [method _process] calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or processing is disabled for scripting ([method set_process]). Only useful for advanced uses to manipulate built-in nodes' behavior. - [b]Warning:[/b] Built-in Nodes rely on the internal processing for their own logic, so changing this value from your code may lead to unexpected behavior. Script access to this internal logic is provided for specific advanced uses, but is unsafe and not supported. + If set to [code]true[/code], enables internal processing for this node. Internal processing happens in isolation from the normal [method _process] calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or processing is disabled for scripting ([method set_process]). + [b]Warning:[/b] Built-in nodes rely on internal processing for their internal logic. Disabling it is unsafe and may lead to unexpected behavior. Use this method if you know what you are doing. </description> </method> <method name="set_process_shortcut_input"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables shortcut processing. Enabled automatically if [method _shortcut_input] is overridden. Any calls to this before [method _ready] will be ignored. + If set to [code]true[/code], enables shortcut processing for this node. + [b]Note:[/b] If [method _shortcut_input] is overridden, this will be automatically enabled before [method _ready] is called. </description> </method> <method name="set_process_unhandled_input"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables unhandled input processing. This is not required for GUI controls! It enables the node to receive all input that was not previously handled (usually by a [Control]). Enabled automatically if [method _unhandled_input] is overridden. Any calls to this before [method _ready] will be ignored. + If set to [code]true[/code], enables unhandled input processing. It enables the node to receive all input that was not previously handled (usually by a [Control]). + [b]Note:[/b] If [method _unhandled_input] is overridden, this will be automatically enabled before [method _ready] is called. Unhandled input processing is also already enabled for GUI controls, such as [Button] and [TextEdit]. </description> </method> <method name="set_process_unhandled_key_input"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Enables unhandled key input processing. Enabled automatically if [method _unhandled_key_input] is overridden. Any calls to this before [method _ready] will be ignored. + If set to [code]true[/code], enables unhandled key input processing. + [b]Note:[/b] If [method _unhandled_key_input] is overridden, this will be automatically enabled before [method _ready] is called. </description> </method> <method name="set_scene_instance_load_placeholder"> <return type="void" /> <param index="0" name="load_placeholder" type="bool" /> <description> - Sets whether this is an instance load placeholder. See [InstancePlaceholder]. + If set to [code]true[/code], the node becomes a [InstancePlaceholder] when packed and instantiated from a [PackedScene]. See also [method get_scene_instance_load_placeholder]. </description> </method> <method name="set_thread_safe"> @@ -870,41 +965,48 @@ <method name="update_configuration_warnings"> <return type="void" /> <description> - Updates the warning displayed for this node in the Scene Dock. - Use [method _get_configuration_warnings] to setup the warning message to display. + Refreshes the warnings displayed for this node in the Scene dock. Use [method _get_configuration_warnings] to customize the warning messages to display. </description> </method> </methods> <members> + <member name="auto_translate_mode" type="int" setter="set_auto_translate_mode" getter="get_auto_translate_mode" enum="Node.AutoTranslateMode" default="0"> + Defines if any text should automatically change to its translated version depending on the current locale (for nodes such as [Label], [RichTextLabel], [Window], etc.). See [enum AutoTranslateMode]. + Also decides if the node's strings should be parsed for POT generation. + </member> <member name="editor_description" type="String" setter="set_editor_description" getter="get_editor_description" default=""""> - Add a custom description to a node. It will be displayed in a tooltip when hovered in editor's scene tree. + An optional description to the node. It will be displayed as a tooltip when hovering over the node in the editor's Scene dock. </member> <member name="multiplayer" type="MultiplayerAPI" setter="" getter="get_multiplayer"> The [MultiplayerAPI] instance associated with this node. See [method SceneTree.get_multiplayer]. [b]Note:[/b] Renaming the node, or moving it in the tree, will not move the [MultiplayerAPI] to the new path, you will have to update this manually. </member> <member name="name" type="StringName" setter="set_name" getter="get_name"> - The name of the node. This name is unique among the siblings (other child nodes from the same parent). When set to an existing name, the node will be automatically renamed. - [b]Note:[/b] Auto-generated names might include the [code]@[/code] character, which is reserved for unique names when using [method add_child]. When setting the name manually, any [code]@[/code] will be removed. + The name of the node. This name must be unique among the siblings (other child nodes from the same parent). When set to an existing sibling's name, the node is automatically renamed. + [b]Note:[/b] When changing the name, the following characters will be replaced with an underscore: ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code] [code]%[/code]). In particular, the [code]@[/code] character is reserved for auto-generated names. See also [method String.validate_node_name]. </member> <member name="owner" type="Node" setter="set_owner" getter="get_owner"> - The node owner. A node can have any ancestor node as owner (i.e. a parent, grandparent, etc. node ascending in the tree). This implies that [method add_child] should be called before setting the owner, so that this relationship of parenting exists. When saving a node (using [PackedScene]), all the nodes it owns will be saved with it. This allows for the creation of complex scene trees, with instancing and subinstancing. - [b]Note:[/b] If you want a child to be persisted to a [PackedScene], you must set [member owner] in addition to calling [method add_child]. This is typically relevant for [url=$DOCS_URL/tutorials/plugins/running_code_in_the_editor.html]tool scripts[/url] and [url=$DOCS_URL/tutorials/plugins/editor/index.html]editor plugins[/url]. If a new node is added to the tree without setting its owner as an ancestor in that tree, it will be visible in the 2D/3D view, but not in the scene tree (and not persisted when packing or saving). + The owner of this node. The owner must be an ancestor of this node. When packing the owner node in a [PackedScene], all the nodes it owns are also saved with it. + [b]Note:[/b] In the editor, nodes not owned by the scene root are usually not displayed in the Scene dock, and will [b]not[/b] be saved. To prevent this, remember to set the owner after calling [method add_child]. See also (see [member unique_name_in_owner]) + </member> + <member name="physics_interpolation_mode" type="int" setter="set_physics_interpolation_mode" getter="get_physics_interpolation_mode" enum="Node.PhysicsInterpolationMode" default="0"> + Allows enabling or disabling physics interpolation per node, offering a finer grain of control than turning physics interpolation on and off globally. See [member ProjectSettings.physics/common/physics_interpolation] and [member SceneTree.physics_interpolation] for the global setting. + [b]Note:[/b] When teleporting a node to a distant position you should temporarily disable interpolation with [method Node.reset_physics_interpolation]. </member> <member name="process_mode" type="int" setter="set_process_mode" getter="get_process_mode" enum="Node.ProcessMode" default="0"> - Can be used to pause or unpause the node, or make the node paused based on the [SceneTree], or make it inherit the process mode from its parent (default). + The node's processing behavior (see [enum ProcessMode]). To check if the node can process in its current mode, use [method can_process]. </member> <member name="process_physics_priority" type="int" setter="set_physics_process_priority" getter="get_physics_process_priority" default="0"> Similar to [member process_priority] but for [constant NOTIFICATION_PHYSICS_PROCESS], [method _physics_process] or the internal version. </member> <member name="process_priority" type="int" setter="set_process_priority" getter="get_process_priority" default="0"> - The node's priority in the execution order of the enabled processing callbacks (i.e. [constant NOTIFICATION_PROCESS], [constant NOTIFICATION_PHYSICS_PROCESS] and their internal counterparts). Nodes whose process priority value is [i]lower[/i] will have their processing callbacks executed first. + The node's execution order of the process callbacks ([method _process], [method _physics_process], and internal processing). Nodes whose priority value is [i]lower[/i] call their process callbacks first, regardless of tree order. </member> <member name="process_thread_group" type="int" setter="set_process_thread_group" getter="get_process_thread_group" enum="Node.ProcessThreadGroup" default="0"> Set the process thread group for this node (basically, whether it receives [constant NOTIFICATION_PROCESS], [constant NOTIFICATION_PHYSICS_PROCESS], [method _process] or [method _physics_process] (and the internal versions) on the main thread or in a sub-thread. By default, the thread group is [constant PROCESS_THREAD_GROUP_INHERIT], which means that this node belongs to the same thread group as the parent node. The thread groups means that nodes in a specific thread group will process together, separate to other thread groups (depending on [member process_thread_group_order]). If the value is set is [constant PROCESS_THREAD_GROUP_SUB_THREAD], this thread group will occur on a sub thread (not the main thread), otherwise if set to [constant PROCESS_THREAD_GROUP_MAIN_THREAD] it will process on the main thread. If there is not a parent or grandparent node set to something other than inherit, the node will belong to the [i]default thread group[/i]. This default group will process on the main thread and its group order is 0. During processing in a sub-thread, accessing most functions in nodes outside the thread group is forbidden (and it will result in an error in debug mode). Use [method Object.call_deferred], [method call_thread_safe], [method call_deferred_thread_group] and the likes in order to communicate from the thread groups to the main thread (or to other thread groups). - To better understand process thread groups, the idea is that any node set to any other value than [constant PROCESS_THREAD_GROUP_INHERIT] will include any children (and grandchildren) nodes set to inherit into its process thread group. this means that the processing of all the nodes in the group will happen together, at the same time as the node including them. + To better understand process thread groups, the idea is that any node set to any other value than [constant PROCESS_THREAD_GROUP_INHERIT] will include any child (and grandchild) nodes set to inherit into its process thread group. This means that the processing of all the nodes in the group will happen together, at the same time as the node including them. </member> <member name="process_thread_group_order" type="int" setter="set_process_thread_group_order" getter="get_process_thread_group_order"> Change the process thread group order. Groups with a lesser order will process before groups with a greater order. This is useful when a large amount of nodes process in sub thread and, afterwards, another group wants to collect their result in the main thread, as an example. @@ -913,26 +1015,26 @@ Set whether the current thread group will process messages (calls to [method call_deferred_thread_group] on threads, and whether it wants to receive them during regular process or physics process callbacks. </member> <member name="scene_file_path" type="String" setter="set_scene_file_path" getter="get_scene_file_path"> - If a scene is instantiated from a file, its topmost node contains the absolute file path from which it was loaded in [member scene_file_path] (e.g. [code]res://levels/1.tscn[/code]). Otherwise, [member scene_file_path] is set to an empty string. + The original scene's file path, if the node has been instantiated from a [PackedScene] file. Only scene root nodes contains this. </member> <member name="unique_name_in_owner" type="bool" setter="set_unique_name_in_owner" getter="is_unique_name_in_owner" default="false"> - Sets this node's name as a unique name in its [member owner]. This allows the node to be accessed as [code]%Name[/code] instead of the full path, from any node within that scene. - If another node with the same owner already had that name declared as unique, that other node's name will no longer be set as having a unique name. + If [code]true[/code], the node can be accessed from any node sharing the same [member owner] or from the [member owner] itself, with special [code]%Name[/code] syntax in [method get_node]. + [b]Note:[/b] If another node with the same [member owner] shares the same [member name] as this node, the other node will no longer be accessible as unique. </member> </members> <signals> <signal name="child_entered_tree"> <param index="0" name="node" type="Node" /> <description> - Emitted when a child node enters the scene tree, either because it entered on its own or because this node entered with it. + Emitted when the child [param node] enters the [SceneTree], usually because this node entered the tree (see [signal tree_entered]), or [method add_child] has been called. This signal is emitted [i]after[/i] the child node's own [constant NOTIFICATION_ENTER_TREE] and [signal tree_entered]. </description> </signal> <signal name="child_exiting_tree"> <param index="0" name="node" type="Node" /> <description> - Emitted when a child node is about to exit the scene tree, either because it is being removed or freed directly, or because this node is exiting the tree. - When this signal is received, the child [param node] is still in the tree and valid. This signal is emitted [i]after[/i] the child node's own [signal tree_exiting] and [constant NOTIFICATION_EXIT_TREE]. + Emitted when the child [param node] is about to exit the [SceneTree], usually because this node is exiting the tree (see [signal tree_exiting]), or because the child [param node] is being removed or freed. + When this signal is received, the child [param node] is still accessible inside the tree. This signal is emitted [i]after[/i] the child node's own [signal tree_exiting] and [constant NOTIFICATION_EXIT_TREE]. </description> </signal> <signal name="child_order_changed"> @@ -940,14 +1042,20 @@ Emitted when the list of children is changed. This happens when child nodes are added, moved or removed. </description> </signal> + <signal name="editor_description_changed"> + <param index="0" name="node" type="Node" /> + <description> + Emitted when the node's editor description field changed. + </description> + </signal> <signal name="ready"> <description> - Emitted when the node is ready. Comes after [method _ready] callback and follows the same rules. + Emitted when the node is considered ready, after [method _ready] is called. </description> </signal> <signal name="renamed"> <description> - Emitted when the node is renamed. + Emitted when the node's [member name] is changed, if the node is inside the tree. </description> </signal> <signal name="replacing_by"> @@ -966,51 +1074,52 @@ <signal name="tree_exited"> <description> Emitted after the node exits the tree and is no longer active. + This signal is emitted [i]after[/i] the related [constant NOTIFICATION_EXIT_TREE] notification. </description> </signal> <signal name="tree_exiting"> <description> - Emitted when the node is still active but about to exit the tree. This is the right place for de-initialization (or a "destructor", if you will). - This signal is emitted [i]before[/i] the related [constant NOTIFICATION_EXIT_TREE] notification. + Emitted when the node is just about to exit the tree. The node is still valid. As such, this is the right place for de-initialization (or a "destructor", if you will). + This signal is emitted [i]after[/i] the node's [method _exit_tree], and [i]before[/i] the related [constant NOTIFICATION_EXIT_TREE]. </description> </signal> </signals> <constants> <constant name="NOTIFICATION_ENTER_TREE" value="10"> - Notification received when the node enters a [SceneTree]. - This notification is emitted [i]before[/i] the related [signal tree_entered]. + Notification received when the node enters a [SceneTree]. See [method _enter_tree]. + This notification is received [i]before[/i] the related [signal tree_entered] signal. </constant> <constant name="NOTIFICATION_EXIT_TREE" value="11"> - Notification received when the node is about to exit a [SceneTree]. - This notification is emitted [i]after[/i] the related [signal tree_exiting]. + Notification received when the node is about to exit a [SceneTree]. See [method _exit_tree]. + This notification is received [i]after[/i] the related [signal tree_exiting] signal. </constant> - <constant name="NOTIFICATION_MOVED_IN_PARENT" value="12" is_deprecated="true"> - [i]Deprecated.[/i] This notification is no longer emitted. Use [constant NOTIFICATION_CHILD_ORDER_CHANGED] instead. + <constant name="NOTIFICATION_MOVED_IN_PARENT" value="12" deprecated="This notification is no longer sent by the engine. Use [constant NOTIFICATION_CHILD_ORDER_CHANGED] instead."> </constant> <constant name="NOTIFICATION_READY" value="13"> Notification received when the node is ready. See [method _ready]. </constant> <constant name="NOTIFICATION_PAUSED" value="14"> - Notification received when the node is paused. + Notification received when the node is paused. See [member process_mode]. </constant> <constant name="NOTIFICATION_UNPAUSED" value="15"> - Notification received when the node is unpaused. + Notification received when the node is unpaused. See [member process_mode]. </constant> <constant name="NOTIFICATION_PHYSICS_PROCESS" value="16"> - Notification received every frame when the physics process flag is set (see [method set_physics_process]). + Notification received from the tree every physics frame when [method is_physics_processing] returns [code]true[/code]. See [method _physics_process]. </constant> <constant name="NOTIFICATION_PROCESS" value="17"> - Notification received every frame when the process flag is set (see [method set_process]). + Notification received from the tree every rendered frame when [method is_processing] returns [code]true[/code]. See [method _process]. </constant> <constant name="NOTIFICATION_PARENTED" value="18"> - Notification received when a node is set as a child of another node. - [b]Note:[/b] This doesn't mean that a node entered the [SceneTree]. + Notification received when the node is set as a child of another node (see [method add_child] and [method add_sibling]). + [b]Note:[/b] This does [i]not[/i] mean that the node entered the [SceneTree]. </constant> <constant name="NOTIFICATION_UNPARENTED" value="19"> - Notification received when a node is unparented (parent removed it from the list of children). + Notification received when the parent node calls [method remove_child] on this node. + [b]Note:[/b] This does [i]not[/i] mean that the node exited the [SceneTree]. </constant> <constant name="NOTIFICATION_SCENE_INSTANTIATED" value="20"> - Notification received by scene owner when its scene is instantiated. + Notification received [i]only[/i] by the newly instantiated scene root node, when [method PackedScene.instantiate] is completed. </constant> <constant name="NOTIFICATION_DRAG_BEGIN" value="21"> Notification received when a drag operation begins. All nodes receive this notification, not only the dragged one. @@ -1022,19 +1131,19 @@ Use [method Viewport.gui_is_drag_successful] to check if the drag succeeded. </constant> <constant name="NOTIFICATION_PATH_RENAMED" value="23"> - Notification received when the node's name or one of its parents' name is changed. This notification is [i]not[/i] received when the node is removed from the scene tree to be added to another parent later on. + Notification received when the node's [member name] or one of its ancestors' [member name] is changed. This notification is [i]not[/i] received when the node is removed from the [SceneTree]. </constant> <constant name="NOTIFICATION_CHILD_ORDER_CHANGED" value="24"> Notification received when the list of children is changed. This happens when child nodes are added, moved or removed. </constant> <constant name="NOTIFICATION_INTERNAL_PROCESS" value="25"> - Notification received every frame when the internal process flag is set (see [method set_process_internal]). + Notification received from the tree every rendered frame when [method is_processing_internal] returns [code]true[/code]. </constant> <constant name="NOTIFICATION_INTERNAL_PHYSICS_PROCESS" value="26"> - Notification received every frame when the internal physics process flag is set (see [method set_physics_process_internal]). + Notification received from the tree every physics frame when [method is_physics_processing_internal] returns [code]true[/code]. </constant> <constant name="NOTIFICATION_POST_ENTER_TREE" value="27"> - Notification received when the node is ready, just before [constant NOTIFICATION_READY] is received. Unlike the latter, it's sent every time the node enters the tree, instead of only once. + Notification received when the node enters the tree, just before [constant NOTIFICATION_READY] may be received. Unlike the latter, it is sent every time the node enters tree, not just once. </constant> <constant name="NOTIFICATION_DISABLED" value="28"> Notification received when the node is disabled. See [constant PROCESS_MODE_DISABLED]. @@ -1042,6 +1151,9 @@ <constant name="NOTIFICATION_ENABLED" value="29"> Notification received when the node is enabled again after being disabled. See [constant PROCESS_MODE_DISABLED]. </constant> + <constant name="NOTIFICATION_RESET_PHYSICS_INTERPOLATION" value="2001"> + Notification received when [method reset_physics_interpolation] is called on the node or its ancestors. + </constant> <constant name="NOTIFICATION_EDITOR_PRE_SAVE" value="9001"> Notification received right before the scene with the node is saved in the editor. This notification is only sent in the Godot editor and will not occur in exported projects. </constant> @@ -1057,11 +1169,11 @@ Implemented for embedded windows and on desktop and web platforms. </constant> <constant name="NOTIFICATION_WM_WINDOW_FOCUS_IN" value="1004"> - Notification received when the node's parent [Window] is focused. This may be a change of focus between two windows of the same engine instance, or from the OS desktop or a third-party application to a window of the game (in which case [constant NOTIFICATION_APPLICATION_FOCUS_IN] is also emitted). + Notification received from the OS when the node's [Window] ancestor is focused. This may be a change of focus between two windows of the same engine instance, or from the OS desktop or a third-party application to a window of the game (in which case [constant NOTIFICATION_APPLICATION_FOCUS_IN] is also received). A [Window] node receives this notification when it is focused. </constant> <constant name="NOTIFICATION_WM_WINDOW_FOCUS_OUT" value="1005"> - Notification received when the node's parent [Window] is defocused. This may be a change of focus between two windows of the same engine instance, or from a window of the game to the OS desktop or a third-party application (in which case [constant NOTIFICATION_APPLICATION_FOCUS_OUT] is also emitted). + Notification received from the OS when the node's [Window] ancestor is defocused. This may be a change of focus between two windows of the same engine instance, or from a window of the game to the OS desktop or a third-party application (in which case [constant NOTIFICATION_APPLICATION_FOCUS_OUT] is also received). A [Window] node receives this notification when it is defocused. </constant> <constant name="NOTIFICATION_WM_CLOSE_REQUEST" value="1006"> @@ -1070,13 +1182,14 @@ </constant> <constant name="NOTIFICATION_WM_GO_BACK_REQUEST" value="1007"> Notification received from the OS when a go back request is sent (e.g. pressing the "Back" button on Android). - Specific to the Android platform. + Implemented only on iOS. </constant> <constant name="NOTIFICATION_WM_SIZE_CHANGED" value="1008"> - Notification received from the OS when the window is resized. + Notification received when the window is resized. + [b]Note:[/b] Only the resized [Window] node receives this notification, and it's not propagated to the child nodes. </constant> <constant name="NOTIFICATION_WM_DPI_CHANGE" value="1009"> - Notification received from the OS when the screen's DPI has been changed. Only implemented on macOS. + Notification received from the OS when the screen's dots per inch (DPI) scale is changed. Only implemented on macOS. </constant> <constant name="NOTIFICATION_VP_MOUSE_ENTER" value="1010"> Notification received when the mouse cursor enters the [Viewport]'s visible area, that is not occluded behind other [Control]s or [Window]s, provided its [member Viewport.gui_disable_input] is [code]false[/code] and regardless if it's currently focused or not. @@ -1086,93 +1199,123 @@ </constant> <constant name="NOTIFICATION_OS_MEMORY_WARNING" value="2009"> Notification received from the OS when the application is exceeding its allocated memory. - Specific to the iOS platform. + Implemented only on iOS. </constant> <constant name="NOTIFICATION_TRANSLATION_CHANGED" value="2010"> - Notification received when translations may have changed. Can be triggered by the user changing the locale. Can be used to respond to language changes, for example to change the UI strings on the fly. Useful when working with the built-in translation support, like [method Object.tr]. + Notification received when translations may have changed. Can be triggered by the user changing the locale, changing [member auto_translate_mode] or when the node enters the scene tree. Can be used to respond to language changes, for example to change the UI strings on the fly. Useful when working with the built-in translation support, like [method Object.tr]. + [b]Note:[/b] This notification is received alongside [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 translations 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 [method is_node_ready]. + [codeblock] + func _notification(what): + if what == NOTIFICATION_TRANSLATION_CHANGED: + if not is_node_ready(): + await ready # Wait until ready signal. + $Label.text = atr("%d Bananas") % banana_counter + [/codeblock] </constant> <constant name="NOTIFICATION_WM_ABOUT" value="2011"> Notification received from the OS when a request for "About" information is sent. - Specific to the macOS platform. + Implemented only on macOS. </constant> <constant name="NOTIFICATION_CRASH" value="2012"> Notification received from Godot's crash handler when the engine is about to crash. - Implemented on desktop platforms if the crash handler is enabled. + Implemented on desktop platforms, if the crash handler is enabled. </constant> <constant name="NOTIFICATION_OS_IME_UPDATE" value="2013"> Notification received from the OS when an update of the Input Method Engine occurs (e.g. change of IME cursor position or composition string). - Specific to the macOS platform. + Implemented only on macOS. </constant> <constant name="NOTIFICATION_APPLICATION_RESUMED" value="2014"> Notification received from the OS when the application is resumed. - Specific to the Android platform. + Specific to the Android and iOS platforms. </constant> <constant name="NOTIFICATION_APPLICATION_PAUSED" value="2015"> Notification received from the OS when the application is paused. - Specific to the Android platform. + Specific to the Android and iOS platforms. + [b]Note:[/b] On iOS, you only have approximately 5 seconds to finish a task started by this signal. If you go over this allotment, iOS will kill the app instead of pausing it. </constant> <constant name="NOTIFICATION_APPLICATION_FOCUS_IN" value="2016"> Notification received from the OS when the application is focused, i.e. when changing the focus from the OS desktop or a thirdparty application to any open window of the Godot instance. - Implemented on desktop platforms. + Implemented on desktop and mobile platforms. </constant> <constant name="NOTIFICATION_APPLICATION_FOCUS_OUT" value="2017"> Notification received from the OS when the application is defocused, i.e. when changing the focus from any open window of the Godot instance to the OS desktop or a thirdparty application. - Implemented on desktop platforms. + Implemented on desktop and mobile platforms. </constant> <constant name="NOTIFICATION_TEXT_SERVER_CHANGED" value="2018"> - Notification received when text server is changed. + Notification received when the [TextServer] is changed. </constant> <constant name="PROCESS_MODE_INHERIT" value="0" enum="ProcessMode"> - Inherits process mode from the node's parent. For the root node, it is equivalent to [constant PROCESS_MODE_PAUSABLE]. Default. + Inherits [member process_mode] from the node's parent. This is the default for any newly created node. </constant> <constant name="PROCESS_MODE_PAUSABLE" value="1" enum="ProcessMode"> - Stops processing when the [SceneTree] is paused (process when unpaused). This is the inverse of [constant PROCESS_MODE_WHEN_PAUSED]. + Stops processing when [member SceneTree.paused] is [code]true[/code]. This is the inverse of [constant PROCESS_MODE_WHEN_PAUSED], and the default for the root node. </constant> <constant name="PROCESS_MODE_WHEN_PAUSED" value="2" enum="ProcessMode"> - Only process when the [SceneTree] is paused (don't process when unpaused). This is the inverse of [constant PROCESS_MODE_PAUSABLE]. + Process [b]only[/b] when [member SceneTree.paused] is [code]true[/code]. This is the inverse of [constant PROCESS_MODE_PAUSABLE]. </constant> <constant name="PROCESS_MODE_ALWAYS" value="3" enum="ProcessMode"> - Always process. Continue processing always, ignoring the [SceneTree]'s paused property. This is the inverse of [constant PROCESS_MODE_DISABLED]. + Always process. Keeps processing, ignoring [member SceneTree.paused]. This is the inverse of [constant PROCESS_MODE_DISABLED]. </constant> <constant name="PROCESS_MODE_DISABLED" value="4" enum="ProcessMode"> - Never process. Completely disables processing, ignoring the [SceneTree]'s paused property. This is the inverse of [constant PROCESS_MODE_ALWAYS]. + Never process. Completely disables processing, ignoring [member SceneTree.paused]. This is the inverse of [constant PROCESS_MODE_ALWAYS]. </constant> <constant name="PROCESS_THREAD_GROUP_INHERIT" value="0" enum="ProcessThreadGroup"> - If the [member process_thread_group] property is sent to this, the node will belong to any parent (or grandparent) node that has a thread group mode that is not inherit. See [member process_thread_group] for more information. + Process this node based on the thread group mode of the first parent (or grandparent) node that has a thread group mode that is not inherit. See [member process_thread_group] for more information. </constant> <constant name="PROCESS_THREAD_GROUP_MAIN_THREAD" value="1" enum="ProcessThreadGroup"> - Process this node (and children nodes set to inherit) on the main thread. See [member process_thread_group] for more information. + Process this node (and child nodes set to inherit) on the main thread. See [member process_thread_group] for more information. </constant> <constant name="PROCESS_THREAD_GROUP_SUB_THREAD" value="2" enum="ProcessThreadGroup"> - Process this node (and children nodes set to inherit) on a sub-thread. See [member process_thread_group] for more information. + Process this node (and child nodes set to inherit) on a sub-thread. See [member process_thread_group] for more information. </constant> <constant name="FLAG_PROCESS_THREAD_MESSAGES" value="1" enum="ProcessThreadMessages" is_bitfield="true"> + Allows this node to process threaded messages created with [method call_deferred_thread_group] right before [method _process] is called. </constant> <constant name="FLAG_PROCESS_THREAD_MESSAGES_PHYSICS" value="2" enum="ProcessThreadMessages" is_bitfield="true"> + Allows this node to process threaded messages created with [method call_deferred_thread_group] right before [method _physics_process] is called. </constant> <constant name="FLAG_PROCESS_THREAD_MESSAGES_ALL" value="3" enum="ProcessThreadMessages" is_bitfield="true"> + Allows this node to process threaded messages created with [method call_deferred_thread_group] right before either [method _process] or [method _physics_process] are called. + </constant> + <constant name="PHYSICS_INTERPOLATION_MODE_INHERIT" value="0" enum="PhysicsInterpolationMode"> + Inherits [member physics_interpolation_mode] from the node's parent. This is the default for any newly created node. + </constant> + <constant name="PHYSICS_INTERPOLATION_MODE_ON" value="1" enum="PhysicsInterpolationMode"> + Enables physics interpolation for this node and for children set to [constant PHYSICS_INTERPOLATION_MODE_INHERIT]. This is the default for the root node. + </constant> + <constant name="PHYSICS_INTERPOLATION_MODE_OFF" value="2" enum="PhysicsInterpolationMode"> + Disables physics interpolation for this node and for children set to [constant PHYSICS_INTERPOLATION_MODE_INHERIT]. </constant> <constant name="DUPLICATE_SIGNALS" value="1" enum="DuplicateFlags"> - Duplicate the node's signals. + Duplicate the node's signal connections. </constant> <constant name="DUPLICATE_GROUPS" value="2" enum="DuplicateFlags"> Duplicate the node's groups. </constant> <constant name="DUPLICATE_SCRIPTS" value="4" enum="DuplicateFlags"> - Duplicate the node's scripts. + Duplicate the node's script (also overriding the duplicated children's scripts, if combined with [constant DUPLICATE_USE_INSTANTIATION]). </constant> <constant name="DUPLICATE_USE_INSTANTIATION" value="8" enum="DuplicateFlags"> - Duplicate using instancing. - An instance stays linked to the original so when the original changes, the instance changes too. + Duplicate using [method PackedScene.instantiate]. If the node comes from a scene saved on disk, re-uses [method PackedScene.instantiate] as the base for the duplicated node and its children. </constant> <constant name="INTERNAL_MODE_DISABLED" value="0" enum="InternalMode"> - Node will not be internal. + The node will not be internal. </constant> <constant name="INTERNAL_MODE_FRONT" value="1" enum="InternalMode"> - Node will be placed at the front of parent's node list, before any non-internal sibling. + The node will be placed at the beginning of the parent's children, before any non-internal sibling. </constant> <constant name="INTERNAL_MODE_BACK" value="2" enum="InternalMode"> - Node will be placed at the back of parent's node list, after any non-internal sibling. + The node will be placed at the end of the parent's children, after any non-internal sibling. + </constant> + <constant name="AUTO_TRANSLATE_MODE_INHERIT" value="0" enum="AutoTranslateMode"> + Inherits [member auto_translate_mode] from the node's parent. This is the default for any newly created node. + </constant> + <constant name="AUTO_TRANSLATE_MODE_ALWAYS" value="1" enum="AutoTranslateMode"> + Always automatically translate. This is the inverse of [constant AUTO_TRANSLATE_MODE_DISABLED], and the default for the root node. + </constant> + <constant name="AUTO_TRANSLATE_MODE_DISABLED" value="2" enum="AutoTranslateMode"> + Never automatically translate. This is the inverse of [constant AUTO_TRANSLATE_MODE_ALWAYS]. + String parsing for POT generation will be skipped for this node and children that are set to [constant AUTO_TRANSLATE_MODE_INHERIT]. </constant> </constants> </class> diff --git a/doc/classes/Node3D.xml b/doc/classes/Node3D.xml index 0b7b982e52..125c7ef3ee 100644 --- a/doc/classes/Node3D.xml +++ b/doc/classes/Node3D.xml @@ -49,7 +49,8 @@ <method name="get_parent_node_3d" qualifiers="const"> <return type="Node3D" /> <description> - Returns the parent [Node3D], or an empty [Object] if no parent exists or parent is not of type [Node3D]. + Returns the parent [Node3D], or [code]null[/code] if no parent exists, the parent is not of type [Node3D], or [member top_level] is [code]true[/code]. + [b]Note:[/b] Calling this method is not equivalent to [code]get_parent() as Node3D[/code], which does not take [member top_level] into account. </description> </method> <method name="get_world_3d" qualifiers="const"> @@ -271,7 +272,7 @@ </methods> <members> <member name="basis" type="Basis" setter="set_basis" getter="get_basis"> - Direct access to the 3x3 basis of the [member transform] property. + Basis of the [member transform] property. Represents the rotation, scale, and shear of this node. </member> <member name="global_basis" type="Basis" setter="set_global_basis" getter="get_global_basis"> Global basis of this node. This is equivalent to [code]global_transform.basis[/code]. diff --git a/doc/classes/NodePath.xml b/doc/classes/NodePath.xml index 553a3913d8..6e0799e796 100644 --- a/doc/classes/NodePath.xml +++ b/doc/classes/NodePath.xml @@ -4,25 +4,33 @@ A pre-parsed scene tree path. </brief_description> <description> - A pre-parsed relative or absolute path in a scene tree, for use with [method Node.get_node] and similar functions. It can reference a node, a resource within a node, or a property of a node or resource. For example, [code]"Path2D/PathFollow2D/Sprite2D:texture:size"[/code] would refer to the [code]size[/code] property of the [code]texture[/code] resource on the node named [code]"Sprite2D"[/code], which is a child of the other named nodes in the path. - You will usually just pass a string to [method Node.get_node] and it will be automatically converted, but you may occasionally want to parse a path ahead of time with [NodePath] or the literal syntax [code]^"path"[/code]. Exporting a [NodePath] variable will give you a node selection widget in the properties panel of the editor, which can often be useful. - A [NodePath] is composed of a list of slash-separated node names (like a filesystem path) and an optional colon-separated list of "subnames" which can be resources or properties. - Some examples of NodePaths include the following: + The [NodePath] built-in [Variant] type represents a path to a node or property in a hierarchy of nodes. It is designed to be efficiently passed into many built-in methods (such as [method Node.get_node], [method Object.set_indexed], [method Tween.tween_property], etc.) without a hard dependence on the node or property they point to. + A node path is represented as a [String] composed of slash-separated ([code]/[/code]) node names and colon-separated ([code]:[/code]) property names (also called "subnames"). Similar to a filesystem path, [code]".."[/code] and [code]"."[/code] are special node names. They refer to the parent node and the current node, respectively. + The following examples are paths relative to the current node: [codeblock] - # No leading slash means it is relative to the current node. - ^"A" # Immediate child A - ^"A/B" # A's child B - ^"." # The current node. - ^".." # The parent node. - ^"../C" # A sibling node C. - ^"../.." # The grandparent node. - # A leading slash means it is absolute from the SceneTree. - ^"/root" # Equivalent to get_tree().get_root(). - ^"/root/Main" # If your main scene's root node were named "Main". - ^"/root/MyAutoload" # If you have an autoloaded node or scene. + ^"A" # Points to the direct child A. + ^"A/B" # Points to A's child B. + ^"." # Points to the current node. + ^".." # Points to the parent node. + ^"../C" # Points to the sibling node C. + ^"../.." # Points to the grandparent node. [/codeblock] - See also [StringName], which is a similar concept for general-purpose string interning. - [b]Note:[/b] In the editor, [NodePath] properties are automatically updated when moving, renaming or deleting a node in the scene tree, but they are never updated at runtime. + A leading slash means the path is absolute, and begins from the [SceneTree]: + [codeblock] + ^"/root" # Points to the SceneTree's root Window. + ^"/root/Title" # May point to the main scene's root node named "Title". + ^"/root/Global" # May point to an autoloaded node or scene named "Global". + [/codeblock] + Despite their name, node paths may also point to a property: + [codeblock] + ^"position" # Points to this object's position. + ^"position:x" # Points to this object's position in the x axis. + ^"Camera3D:rotation:y" # Points to the child Camera3D and its y rotation. + ^"/root:size:x" # Points to the root Window and its width. + [/codeblock] + Node paths cannot check whether they are valid and may point to nodes or properties that do not exist. Their meaning depends entirely on the context in which they're used. + You usually do not have to worry about the [NodePath] type, as strings are automatically converted to the type when necessary. There are still times when defining node paths is useful. For example, exported [NodePath] properties allow you to easily select any node within the currently edited scene. They are also automatically updated when moving, renaming or deleting nodes in the scene tree editor. See also [annotation @GDScript.@export_node_path]. + See also [StringName], which is a similar type designed for optimised strings. [b]Note:[/b] In a boolean context, a [NodePath] will evaluate to [code]false[/code] if it is empty ([code]NodePath("")[/code]). Otherwise, a [NodePath] will always evaluate to [code]true[/code]. </description> <tutorials> @@ -39,30 +47,35 @@ <return type="NodePath" /> <param index="0" name="from" type="NodePath" /> <description> - Constructs a [NodePath] as a copy of the given [NodePath]. [code]NodePath("example")[/code] is equivalent to [code]^"example"[/code]. + Constructs a [NodePath] as a copy of the given [NodePath]. </description> </constructor> <constructor name="NodePath"> <return type="NodePath" /> <param index="0" name="from" type="String" /> <description> - Creates a NodePath from a string, e.g. [code]"Path2D/PathFollow2D/Sprite2D:texture:size"[/code]. A path is absolute if it starts with a slash. Absolute paths are only valid in the global scene tree, not within individual scenes. In a relative path, [code]"."[/code] and [code]".."[/code] indicate the current node and its parent. - The "subnames" optionally included after the path to the target node can point to resources or properties, and can also be nested. - Examples of valid NodePaths (assuming that those nodes exist and have the referenced resources or properties): + Constructs a [NodePath] from a [String]. The created path is absolute if prefixed with a slash (see [method is_absolute]). + The "subnames" optionally included after the path to the target node can point to properties, and can also be nested. + Examples of strings that could be node paths: [codeblock] # Points to the Sprite2D node. - "Path2D/PathFollow2D/Sprite2D" + "Level/RigidBody2D/Sprite2D" + # Points to the Sprite2D node and its "texture" resource. - # get_node() would retrieve "Sprite2D", while get_node_and_resource() + # get_node() would retrieve the Sprite2D, while get_node_and_resource() # would retrieve both the Sprite2D node and the "texture" resource. - "Path2D/PathFollow2D/Sprite2D:texture" + "Level/RigidBody2D/Sprite2D:texture" + # Points to the Sprite2D node and its "position" property. - "Path2D/PathFollow2D/Sprite2D:position" + "Level/RigidBody2D/Sprite2D:position" + # Points to the Sprite2D node and the "x" component of its "position" property. - "Path2D/PathFollow2D/Sprite2D:position:x" - # Absolute path (from "root") - "/root/Level/Path2D" + "Level/RigidBody2D/Sprite2D:position:x" + + # Points to the RigidBody2D node as an absolute path beginning from the SceneTree. + "/root/Level/RigidBody2D" [/codeblock] + [b]Note:[/b] In GDScript, it's also possible to convert a constant string into a node path by prefixing it with [code]^[/code]. [code]^"path/to/node"[/code] is equivalent to [code]NodePath("path/to/node")[/code]. </description> </constructor> </constructors> @@ -70,21 +83,23 @@ <method name="get_as_property_path" qualifiers="const"> <return type="NodePath" /> <description> - Returns a node path with a colon character ([code]:[/code]) prepended, transforming it to a pure property path with no node name (defaults to resolving from the current node). + Returns a copy of this node path with a colon character ([code]:[/code]) prefixed, transforming it to a pure property path with no node names (relative to the current node). [codeblocks] [gdscript] - # This will be parsed as a node path to the "x" property in the "position" node. - var node_path = NodePath("position:x") - # This will be parsed as a node path to the "x" component of the "position" property in the current node. + # node_path points to the "x" property of the child node named "position". + var node_path = ^"position:x" + + # property_path points to the "position" in the "x" axis of this node. var property_path = node_path.get_as_property_path() - print(property_path) # :position:x + print(property_path) # Prints ":position:x" [/gdscript] [csharp] - // This will be parsed as a node path to the "x" property in the "position" node. + // nodePath points to the "x" property of the child node named "position". var nodePath = new NodePath("position:x"); - // This will be parsed as a node path to the "x" component of the "position" property in the current node. + + // propertyPath points to the "position" in the "x" axis of this node. NodePath propertyPath = nodePath.GetAsPropertyPath(); - GD.Print(propertyPath); // :position:x + GD.Print(propertyPath); // Prints ":position:x". [/csharp] [/codeblocks] </description> @@ -92,21 +107,21 @@ <method name="get_concatenated_names" qualifiers="const"> <return type="StringName" /> <description> - Returns all paths concatenated with a slash character ([code]/[/code]) as separator without subnames. + Returns all node names concatenated with a slash character ([code]/[/code]) as a single [StringName]. </description> </method> <method name="get_concatenated_subnames" qualifiers="const"> <return type="StringName" /> <description> - Returns all subnames concatenated with a colon character ([code]:[/code]) as separator, i.e. the right side of the first colon in a node path. + Returns all property subnames concatenated with a colon character ([code]:[/code]) as a single [StringName]. [codeblocks] [gdscript] - var node_path = NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path") - print(node_path.get_concatenated_subnames()) # texture:load_path + var node_path = ^"Sprite2D:texture:resource_name" + print(node_path.get_concatenated_subnames()) # Prints "texture:resource_name". [/gdscript] [csharp] - var nodePath = new NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path"); - GD.Print(nodePath.GetConcatenatedSubnames()); // texture:load_path + var nodePath = new NodePath("Sprite2D:texture:resource_name"); + GD.Print(nodePath.GetConcatenatedSubnames()); // Prints "texture:resource_name". [/csharp] [/codeblocks] </description> @@ -115,19 +130,19 @@ <return type="StringName" /> <param index="0" name="idx" type="int" /> <description> - Gets the node name indicated by [param idx] (0 to [method get_name_count] - 1). + Returns the node name indicated by [param idx], starting from 0. If [param idx] is out of bounds, an error is generated. See also [method get_subname_count] and [method get_name_count]. [codeblocks] [gdscript] - var node_path = NodePath("Path2D/PathFollow2D/Sprite2D") - print(node_path.get_name(0)) # Path2D - print(node_path.get_name(1)) # PathFollow2D - print(node_path.get_name(2)) # Sprite + var sprite_path = NodePath("../RigidBody2D/Sprite2D") + print(sprite_path.get_name(0)) # Prints "..". + print(sprite_path.get_name(1)) # Prints "RigidBody2D". + print(sprite_path.get_name(2)) # Prints "Sprite". [/gdscript] [csharp] - var nodePath = new NodePath("Path2D/PathFollow2D/Sprite2D"); - GD.Print(nodePath.GetName(0)); // Path2D - GD.Print(nodePath.GetName(1)); // PathFollow2D - GD.Print(nodePath.GetName(2)); // Sprite + var spritePath = new NodePath("../RigidBody2D/Sprite2D"); + GD.Print(spritePath.GetName(0)); // Prints "..". + GD.Print(spritePath.GetName(1)); // Prints "PathFollow2D". + GD.Print(spritePath.GetName(2)); // Prints "Sprite". [/csharp] [/codeblocks] </description> @@ -135,25 +150,25 @@ <method name="get_name_count" qualifiers="const"> <return type="int" /> <description> - Gets the number of node names which make up the path. Subnames (see [method get_subname_count]) are not included. - For example, [code]"Path2D/PathFollow2D/Sprite2D"[/code] has 3 names. + Returns the number of node names in the path. Property subnames are not included. + For example, [code]"../RigidBody2D/Sprite2D:texture"[/code] contains 3 node names. </description> </method> <method name="get_subname" qualifiers="const"> <return type="StringName" /> <param index="0" name="idx" type="int" /> <description> - Gets the resource or property name indicated by [param idx] (0 to [method get_subname_count] - 1). + Returns the property name indicated by [param idx], starting from 0. If [param idx] is out of bounds, an error is generated. See also [method get_subname_count]. [codeblocks] [gdscript] - var node_path = NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path") - print(node_path.get_subname(0)) # texture - print(node_path.get_subname(1)) # load_path + var path_to_name = NodePath("Sprite2D:texture:resource_name") + print(path_to_name.get_subname(0)) # Prints "texture". + print(path_to_name.get_subname(1)) # Prints "resource_name". [/gdscript] [csharp] - var nodePath = new NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path"); - GD.Print(nodePath.GetSubname(0)); // texture - GD.Print(nodePath.GetSubname(1)); // load_path + var pathToName = new NodePath("Sprite2D:texture:resource_name"); + GD.Print(pathToName.GetSubname(0)); // Prints "texture". + GD.Print(pathToName.GetSubname(1)); // Prints "resource_name". [/csharp] [/codeblocks] </description> @@ -161,26 +176,37 @@ <method name="get_subname_count" qualifiers="const"> <return type="int" /> <description> - Gets the number of resource or property names ("subnames") in the path. Each subname is listed after a colon character ([code]:[/code]) in the node path. - For example, [code]"Path2D/PathFollow2D/Sprite2D:texture:load_path"[/code] has 2 subnames. + Returns the number of property names ("subnames") in the path. Each subname in the node path is listed after a colon character ([code]:[/code]). + For example, [code]"Level/RigidBody2D/Sprite2D:texture:resource_name"[/code] contains 2 subnames. </description> </method> <method name="hash" qualifiers="const"> <return type="int" /> <description> - Returns the 32-bit hash value representing the [NodePath]'s contents. + Returns the 32-bit hash value representing the node path's contents. + [b]Note:[/b] Node paths with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. Node paths with different hash values are guaranteed to be different. </description> </method> <method name="is_absolute" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the node path is absolute (as opposed to relative), which means that it starts with a slash character ([code]/[/code]). Absolute node paths can be used to access the root node ([code]"/root"[/code]) or autoloads (e.g. [code]"/global"[/code] if a "global" autoload was registered). + Returns [code]true[/code] if the node path is absolute. Unlike a relative path, an absolute path is represented by a leading slash character ([code]/[/code]) and always begins from the [SceneTree]. It can be used to reliably access nodes from the root node (e.g. [code]"/root/Global"[/code] if an autoload named "Global" exists). </description> </method> <method name="is_empty" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the node path is empty. + Returns [code]true[/code] if the node path has been constructed from an empty [String] ([code]""[/code]). + </description> + </method> + <method name="slice" qualifiers="const"> + <return type="NodePath" /> + <param index="0" name="begin" type="int" /> + <param index="1" name="end" type="int" default="2147483647" /> + <description> + Returns the slice of the [NodePath], from [param begin] (inclusive) to [param end] (exclusive), as a new [NodePath]. + The absolute value of [param begin] and [param end] will be clamped to the sum of [method get_name_count] and [method get_subname_count], so the default value for [param end] makes it slice to the end of the [NodePath] by default (i.e. [code]path.slice(1)[/code] is a shorthand for [code]path.slice(1, path.get_name_count() + path.get_subname_count())[/code]). + If either [param begin] or [param end] are negative, they will be relative to the end of the [NodePath] (i.e. [code]path.slice(0, -2)[/code] is a shorthand for [code]path.slice(0, path.get_name_count() + path.get_subname_count() - 2)[/code]). </description> </method> </methods> @@ -196,7 +222,7 @@ <return type="bool" /> <param index="0" name="right" type="NodePath" /> <description> - Returns [code]true[/code] if two node paths are equal, i.e. all node names in the path are the same and in the same order. + Returns [code]true[/code] if two node paths are equal, that is, they are composed of the same node names and subnames in the same order. </description> </operator> </operators> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index ad89efb256..bd1bd9afa7 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -4,8 +4,8 @@ Provides access to common operating system functionalities. </brief_description> <description> - This class wraps the most common functionalities for communicating with the host operating system, such as the video driver, delays, environment variables, execution of binaries, command line, etc. - [b]Note:[/b] In Godot 4, [OS] functions related to window management were moved to the [DisplayServer] singleton. + The [OS] class wraps the most common functionalities for communicating with the host operating system, such as the video driver, delays, environment variables, execution of binaries, command line, etc. + [b]Note:[/b] In Godot 4, [OS] functions related to window management, clipboard, and TTS were moved to the [DisplayServer] singleton (and the [Window] class). Functions related to time were removed and are only available in the [Time] class. </description> <tutorials> <link title="OS Test Demo">https://godotengine.org/asset-library/asset/677</link> @@ -16,13 +16,13 @@ <param index="0" name="text" type="String" /> <param index="1" name="title" type="String" default=""Alert!"" /> <description> - Displays a modal dialog box using the host OS' facilities. Execution is blocked until the dialog is closed. + Displays a modal dialog box using the host platform's implementation. The engine execution is blocked until the dialog is closed. </description> </method> <method name="close_midi_inputs"> <return type="void" /> <description> - Shuts down system MIDI driver. + Shuts down the system MIDI driver. Godot will no longer receive [InputEventMIDI]. See also [method open_midi_inputs] and [method get_connected_midi_inputs]. [b]Note:[/b] This method is implemented on Linux, macOS and Windows. </description> </method> @@ -30,7 +30,8 @@ <return type="void" /> <param index="0" name="message" type="String" /> <description> - Crashes the engine (or the editor if called within a [code]@tool[/code] script). This should [i]only[/i] be used for testing the system's crash handler, not for any other purpose. For general error reporting, use (in order of preference) [method @GDScript.assert], [method @GlobalScope.push_error] or [method alert]. See also [method kill]. + Crashes the engine (or the editor if called within a [code]@tool[/code] script). See also [method kill]. + [b]Note:[/b] This method should [i]only[/i] be used for testing the system's crash handler, not for any other purpose. For general error reporting, use (in order of preference) [method @GDScript.assert], [method @GlobalScope.push_error], or [method alert]. </description> </method> <method name="create_instance"> @@ -38,8 +39,9 @@ <param index="0" name="arguments" type="PackedStringArray" /> <description> Creates a new instance of Godot that runs independently. The [param arguments] are used in the given order and separated by a space. - If the process creation succeeds, the method will return the new process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). If the process creation fails, the method will return [code]-1[/code]. - [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. + If the process is successfully created, this method returns the new process' ID, which you can use to monitor the process (and potentially terminate it with [method kill]). If the process cannot be created, this method returns [code]-1[/code]. + See [method create_process] if you wish to run a different process. + [b]Note:[/b] This method is implemented on Android, Linux, macOS and Windows. </description> </method> <method name="create_process"> @@ -48,9 +50,9 @@ <param index="1" name="arguments" type="PackedStringArray" /> <param index="2" name="open_console" type="bool" default="false" /> <description> - Creates a new process that runs independently of Godot. It will not terminate if Godot terminates. The path specified in [param path] must exist and be executable file or macOS .app bundle. Platform path resolution will be used. The [param arguments] are used in the given order and separated by a space. - On Windows, if [param open_console] is [code]true[/code] and the process is a console app, a new terminal window will be opened. This is ignored on other platforms. - If the process creation succeeds, the method will return the new process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). If the process creation fails, the method will return [code]-1[/code]. + Creates a new process that runs independently of Godot. It will not terminate when Godot terminates. The path specified in [param path] must exist and be an executable file or macOS [code].app[/code] bundle. The path is resolved based on the current platform. The [param arguments] are used in the given order and separated by a space. + On Windows, if [param open_console] is [code]true[/code] and the process is a console app, a new terminal window will be opened. + If the process is successfully created, this method returns its process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). Otherwise, this method returns [code]-1[/code]. For example, running another instance of the project: [codeblocks] [gdscript] @@ -61,7 +63,7 @@ [/csharp] [/codeblocks] See [method execute] if you wish to run an external command and retrieve the results. - [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. + [b]Note:[/b] This method is implemented on Android, Linux, macOS, and Windows. [b]Note:[/b] On macOS, sandboxed applications are limited to run only embedded helper executables, specified during export or system .app bundle, system .app bundles will ignore arguments. </description> </method> @@ -69,8 +71,8 @@ <return type="void" /> <param index="0" name="msec" type="int" /> <description> - Delays execution of the current thread by [param msec] milliseconds. [param msec] must be greater than or equal to [code]0[/code]. Otherwise, [method delay_msec] will do nothing and will print an error message. - [b]Note:[/b] [method delay_msec] is a [i]blocking[/i] way to delay code execution. To delay code execution in a non-blocking way, see [method SceneTree.create_timer]. Awaiting with [method SceneTree.create_timer] will delay the execution of code placed below the [code]await[/code] without affecting the rest of the project (or editor, for [EditorPlugin]s and [EditorScript]s). + Delays execution of the current thread by [param msec] milliseconds. [param msec] must be greater than or equal to [code]0[/code]. Otherwise, [method delay_msec] does nothing and prints an error message. + [b]Note:[/b] [method delay_msec] is a [i]blocking[/i] way to delay code execution. To delay code execution in a non-blocking way, you may use [method SceneTree.create_timer]. Awaiting with [SceneTreeTimer] delays the execution of code placed below the [code]await[/code] without affecting the rest of the project (or editor, for [EditorPlugin]s and [EditorScript]s). [b]Note:[/b] When [method delay_msec] is called on the main thread, it will freeze the project and will prevent it from redrawing and registering input until the delay has passed. When using [method delay_msec] as part of an [EditorPlugin] or [EditorScript], it will freeze the editor but won't freeze the project if it is currently running (since the project is an independent child process). </description> </method> @@ -78,8 +80,8 @@ <return type="void" /> <param index="0" name="usec" type="int" /> <description> - Delays execution of the current thread by [param usec] microseconds. [param usec] must be greater than or equal to [code]0[/code]. Otherwise, [method delay_usec] will do nothing and will print an error message. - [b]Note:[/b] [method delay_usec] is a [i]blocking[/i] way to delay code execution. To delay code execution in a non-blocking way, see [method SceneTree.create_timer]. Awaiting with [method SceneTree.create_timer] will delay the execution of code placed below the [code]await[/code] without affecting the rest of the project (or editor, for [EditorPlugin]s and [EditorScript]s). + Delays execution of the current thread by [param usec] microseconds. [param usec] must be greater than or equal to [code]0[/code]. Otherwise, [method delay_usec] does nothing and prints an error message. + [b]Note:[/b] [method delay_usec] is a [i]blocking[/i] way to delay code execution. To delay code execution in a non-blocking way, you may use [method SceneTree.create_timer]. Awaiting with a [SceneTreeTimer] delays the execution of code placed below the [code]await[/code] without affecting the rest of the project (or editor, for [EditorPlugin]s and [EditorScript]s). [b]Note:[/b] When [method delay_usec] is called on the main thread, it will freeze the project and will prevent it from redrawing and registering input until the delay has passed. When using [method delay_usec] as part of an [EditorPlugin] or [EditorScript], it will freeze the editor but won't freeze the project if it is currently running (since the project is an independent child process). </description> </method> @@ -91,10 +93,11 @@ <param index="3" name="read_stderr" type="bool" default="false" /> <param index="4" name="open_console" type="bool" default="false" /> <description> - Executes a command. The file specified in [param path] must exist and be executable. Platform path resolution will be used. The [param arguments] are used in the given order, separated by spaces, and wrapped in quotes. If an [param output] [Array] is provided, the complete shell output of the process will be appended as a single [String] element in [param output]. If [param read_stderr] is [code]true[/code], the output to the standard error stream will be included too. - On Windows, if [param open_console] is [code]true[/code] and the process is a console app, a new terminal window will be opened. This is ignored on other platforms. - If the command is successfully executed, the method will return the exit code of the command, or [code]-1[/code] if it fails. - [b]Note:[/b] The Godot thread will pause its execution until the executed command terminates. Use [Thread] to create a separate thread that will not pause the Godot thread, or use [method create_process] to create a completely independent process. + Executes the given process in a [i]blocking[/i] way. The file specified in [param path] must exist and be executable. The system path resolution will be used. The [param arguments] are used in the given order, separated by spaces, and wrapped in quotes. + If an [param output] array is provided, the complete shell output of the process is appended to [param output] as a single [String] element. If [param read_stderr] is [code]true[/code], the output to the standard error stream is also appended to the array. + On Windows, if [param open_console] is [code]true[/code] and the process is a console app, a new terminal window is opened. + This method returns the exit code of the command, or [code]-1[/code] if the process fails to execute. + [b]Note:[/b] The main thread will be blocked until the executed command terminates. Use [Thread] to create a separate thread that will not block the main thread, or use [method create_process] to create a completely independent process. For example, to retrieve a list of the working directory's contents: [codeblocks] [gdscript] @@ -117,24 +120,58 @@ OS.Execute("CMD.exe", new string[] {"/C", "cd %TEMP% && dir"}, output); [/csharp] [/codeblocks] - [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. + [b]Note:[/b] This method is implemented on Android, Linux, macOS, and Windows. [b]Note:[/b] To execute a Windows command interpreter built-in command, specify [code]cmd.exe[/code] in [param path], [code]/c[/code] as the first argument, and the desired command as the second argument. [b]Note:[/b] To execute a PowerShell built-in command, specify [code]powershell.exe[/code] in [param path], [code]-Command[/code] as the first argument, and the desired command as the second argument. [b]Note:[/b] To execute a Unix shell built-in command, specify shell executable name in [param path], [code]-c[/code] as the first argument, and the desired command as the second argument. [b]Note:[/b] On macOS, sandboxed applications are limited to run only embedded helper executables, specified during export. + [b]Note:[/b] On Android, system commands such as [code]dumpsys[/code] can only be run on a rooted device. + </description> + </method> + <method name="execute_with_pipe"> + <return type="Dictionary" /> + <param index="0" name="path" type="String" /> + <param index="1" name="arguments" type="PackedStringArray" /> + <description> + Creates a new process that runs independently of Godot with redirected IO. It will not terminate when Godot terminates. The path specified in [param path] must exist and be an executable file or macOS [code].app[/code] bundle. The path is resolved based on the current platform. The [param arguments] are used in the given order and separated by a space. + If the process cannot be created, this method returns an empty [Dictionary]. Otherwise, this method returns a [Dictionary] with the following keys: + - [code]"stdio"[/code] - [FileAccess] to access the process stdin and stdout pipes (read/write). + - [code]"stderr"[/code] - [FileAccess] to access the process stderr pipe (read only). + - [code]"pid"[/code] - Process ID as an [int], which you can use to monitor the process (and potentially terminate it with [method kill]). + [b]Note:[/b] This method is implemented on Android, Linux, macOS, and Windows. + [b]Note:[/b] To execute a Windows command interpreter built-in command, specify [code]cmd.exe[/code] in [param path], [code]/c[/code] as the first argument, and the desired command as the second argument. + [b]Note:[/b] To execute a PowerShell built-in command, specify [code]powershell.exe[/code] in [param path], [code]-Command[/code] as the first argument, and the desired command as the second argument. + [b]Note:[/b] To execute a Unix shell built-in command, specify shell executable name in [param path], [code]-c[/code] as the first argument, and the desired command as the second argument. + [b]Note:[/b] On macOS, sandboxed applications are limited to run only embedded helper executables, specified during export or system .app bundle, system .app bundles will ignore arguments. </description> </method> <method name="find_keycode_from_string" qualifiers="const"> <return type="int" enum="Key" /> <param index="0" name="string" type="String" /> <description> - Returns the keycode of the given string (e.g. "Escape"). + Finds the keycode for the given string. The returned values are equivalent to the [enum Key] constants. + [codeblocks] + [gdscript] + print(OS.find_keycode_from_string("C")) # Prints 67 (KEY_C) + print(OS.find_keycode_from_string("Escape")) # Prints 4194305 (KEY_ESCAPE) + print(OS.find_keycode_from_string("Shift+Tab")) # Prints 37748738 (KEY_MASK_SHIFT | KEY_TAB) + print(OS.find_keycode_from_string("Unknown")) # Prints 0 (KEY_NONE) + [/gdscript] + [csharp] + GD.Print(OS.FindKeycodeFromString("C")); // Prints C (Key.C) + GD.Print(OS.FindKeycodeFromString("Escape")); // Prints Escape (Key.Escape) + GD.Print(OS.FindKeycodeFromString("Shift+Tab")); // Prints 37748738 (KeyModifierMask.MaskShift | Key.Tab) + GD.Print(OS.FindKeycodeFromString("Unknown")); // Prints None (Key.None) + [/csharp] + [/codeblocks] + See also [method get_keycode_string]. </description> </method> <method name="get_cache_dir" qualifiers="const"> <return type="String" /> <description> - Returns the [i]global[/i] cache data directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the [code]XDG_CACHE_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_config_dir] and [method get_data_dir]. + Returns the [i]global[/i] cache data directory according to the operating system's standards. + On the Linux/BSD platform, this path can be overridden by setting the [code]XDG_CACHE_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_config_dir] and [method get_data_dir]. Not to be confused with [method get_user_data_dir], which returns the [i]project-specific[/i] user data path. </description> </method> @@ -145,12 +182,12 @@ Command-line arguments can be written in any form, including both [code]--key value[/code] and [code]--key=value[/code] forms so they can be properly parsed, as long as custom command-line arguments do not conflict with engine arguments. You can also incorporate environment variables using the [method get_environment] method. You can set [member ProjectSettings.editor/run/main_run_args] to define command-line arguments to be passed by the editor when running the project. - Here's a minimal example on how to parse command-line arguments into a dictionary using the [code]--key=value[/code] form for arguments: + Here's a minimal example on how to parse command-line arguments into a [Dictionary] using the [code]--key=value[/code] form for arguments: [codeblocks] [gdscript] var arguments = {} for argument in OS.get_cmdline_args(): - if argument.find("=") > -1: + if argument.contains("="): var key_value = argument.split("=") arguments[key_value[0].lstrip("--")] = key_value[1] else: @@ -162,7 +199,7 @@ var arguments = new Godot.Collections.Dictionary(); foreach (var argument in OS.GetCmdlineArgs()) { - if (argument.Find("=") > -1) + if (argument.Contains('=')) { string[] keyValue = argument.Split("="); arguments[keyValue[0].LStrip("--")] = keyValue[1]; @@ -176,91 +213,108 @@ } [/csharp] [/codeblocks] - [b]Note:[/b] Passing custom user arguments directly is not recommended, as the engine may discard or modify them. Instead, the best way is to use the standard UNIX double dash ([code]--[/code]) and then pass custom arguments, which the engine itself will ignore. These can be read via [method get_cmdline_user_args]. + [b]Note:[/b] Passing custom user arguments directly is not recommended, as the engine may discard or modify them. Instead, pass the standard UNIX double dash ([code]--[/code]) and then the custom arguments, which the engine will ignore by design. These can be read via [method get_cmdline_user_args]. </description> </method> <method name="get_cmdline_user_args"> <return type="PackedStringArray" /> <description> - Similar to [method get_cmdline_args], but this returns the user arguments (any argument passed after the double dash [code]--[/code] or double plus [code]++[/code] argument). These are left untouched by Godot for the user. [code]++[/code] can be used in situations where [code]--[/code] is intercepted by another program (such as [code]startx[/code]). - For example, in the command line below, [code]--fullscreen[/code] will not be returned in [method get_cmdline_user_args] and [code]--level 1[/code] will only be returned in [method get_cmdline_user_args]: + Returns the command-line user arguments passed to the engine. User arguments are ignored by the engine and reserved for the user. They are passed after the double dash [code]--[/code] argument. [code]++[/code] may be used when [code]--[/code] is intercepted by another program (such as [code]startx[/code]). [codeblock] - godot --fullscreen -- --level 1 - # Or: - godot --fullscreen ++ --level 1 + # Godot has been executed with the following command: + # godot --fullscreen -- --level=2 --hardcore + + OS.get_cmdline_args() # Returns ["--fullscreen", "--level=2", "--hardcore"] + OS.get_cmdline_user_args() # Returns ["--level=2", "--hardcore"] [/codeblock] + To get all passed arguments, use [method get_cmdline_args]. </description> </method> <method name="get_config_dir" qualifiers="const"> <return type="String" /> <description> - Returns the [i]global[/i] user configuration directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the [code]XDG_CONFIG_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_data_dir]. + Returns the [i]global[/i] user configuration directory according to the operating system's standards. + On the Linux/BSD platform, this path can be overridden by setting the [code]XDG_CONFIG_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_data_dir]. Not to be confused with [method get_user_data_dir], which returns the [i]project-specific[/i] user data path. </description> </method> <method name="get_connected_midi_inputs"> <return type="PackedStringArray" /> <description> - Returns an array of MIDI device names. - The returned array will be empty if the system MIDI driver has not previously been initialized with [method open_midi_inputs]. + Returns an array of connected MIDI device names, if they exist. Returns an empty array if the system MIDI driver has not previously been initialized with [method open_midi_inputs]. See also [method close_midi_inputs]. [b]Note:[/b] This method is implemented on Linux, macOS and Windows. </description> </method> <method name="get_data_dir" qualifiers="const"> <return type="String" /> <description> - Returns the [i]global[/i] user data directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the [code]XDG_DATA_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_config_dir]. + Returns the [i]global[/i] user data directory according to the operating system's standards. + On the Linux/BSD platform, this path can be overridden by setting the [code]XDG_DATA_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_config_dir]. Not to be confused with [method get_user_data_dir], which returns the [i]project-specific[/i] user data path. </description> </method> <method name="get_distribution_name" qualifiers="const"> <return type="String" /> <description> - Returns the name of the distribution for Linux and BSD platforms (e.g. Ubuntu, Manjaro, OpenBSD, etc.). - Returns the same value as [method get_name] for stock Android ROMs, but attempts to return the custom ROM name for popular Android derivatives such as LineageOS. + Returns the name of the distribution for Linux and BSD platforms (e.g. "Ubuntu", "Manjaro", "OpenBSD", etc.). + Returns the same value as [method get_name] for stock Android ROMs, but attempts to return the custom ROM name for popular Android derivatives such as "LineageOS". Returns the same value as [method get_name] for other platforms. - [b]Note:[/b] This method is not supported on the web platform. It returns an empty string. + [b]Note:[/b] This method is not supported on the Web platform. It returns an empty string. </description> </method> <method name="get_environment" qualifiers="const"> <return type="String" /> <param index="0" name="variable" type="String" /> <description> - Returns the value of an environment variable. Returns an empty string if the environment variable doesn't exist. + Returns the value of the given environment variable, or an empty string if [param variable] doesn't exist. [b]Note:[/b] Double-check the casing of [param variable]. Environment variable names are case-sensitive on all platforms except Windows. + [b]Note:[/b] On macOS, applications do not have access to shell environment variables. </description> </method> <method name="get_executable_path" qualifiers="const"> <return type="String" /> <description> - Returns the path to the current engine executable. + Returns the file path to the current engine executable. [b]Note:[/b] On macOS, always use [method create_instance] instead of relying on executable path. </description> </method> <method name="get_granted_permissions" qualifiers="const"> <return type="PackedStringArray" /> <description> - On Android devices: With this function, you can get the list of dangerous permissions that have been granted. - On macOS (sandboxed applications only): This function returns the list of user selected folders accessible to the application. Use native file dialog to request folder access permission. + On Android devices: Returns the list of dangerous permissions that have been granted. + On macOS: Returns the list of user selected folders accessible to the application (sandboxed applications only). Use the native file dialog to request folder access permission. </description> </method> <method name="get_keycode_string" qualifiers="const"> <return type="String" /> <param index="0" name="code" type="int" enum="Key" /> <description> - Returns the given keycode as a string (e.g. Return values: [code]"Escape"[/code], [code]"Shift+Escape"[/code]). - See also [member InputEventKey.keycode] and [method InputEventKey.get_keycode_with_modifiers]. + Returns the given keycode as a [String]. + [codeblocks] + [gdscript] + print(OS.get_keycode_string(KEY_C)) # Prints "C" + print(OS.get_keycode_string(KEY_ESCAPE)) # Prints "Escape" + print(OS.get_keycode_string(KEY_MASK_SHIFT | KEY_TAB)) # Prints "Shift+Tab" + [/gdscript] + [csharp] + GD.Print(OS.GetKeycodeString(Key.C)); // Prints "C" + GD.Print(OS.GetKeycodeString(Key.Escape)); // Prints "Escape" + GD.Print(OS.GetKeycodeString((Key)KeyModifierMask.MaskShift | Key.Tab)); // Prints "Shift+Tab" + [/csharp] + [/codeblocks] + See also [method find_keycode_from_string], [member InputEventKey.keycode], and [method InputEventKey.get_keycode_with_modifiers]. </description> </method> <method name="get_locale" qualifiers="const"> <return type="String" /> <description> - Returns the host OS locale as a string of the form [code]language_Script_COUNTRY_VARIANT@extra[/code]. If you want only the language code and not the fully specified locale from the OS, you can use [method get_locale_language]. - [code]language[/code] - 2 or 3-letter [url=https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes]language code[/url], in lower case. - [code skip-lint]Script[/code] - optional, 4-letter [url=https://en.wikipedia.org/wiki/ISO_15924]script code[/url], in title case. - [code]COUNTRY[/code] - optional, 2 or 3-letter [url=https://en.wikipedia.org/wiki/ISO_3166-1]country code[/url], in upper case. - [code]VARIANT[/code] - optional, language variant, region and sort order. Variant can have any number of underscored keywords. - [code]extra[/code] - optional, semicolon separated list of additional key words. Currency, calendar, sort order and numbering system information. + Returns the host OS locale as a [String] of the form [code]language_Script_COUNTRY_VARIANT@extra[/code]. Every substring after [code]language[/code] is optional and may not exist. + - [code]language[/code] - 2 or 3-letter [url=https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes]language code[/url], in lower case. + - [code skip-lint]Script[/code] - 4-letter [url=https://en.wikipedia.org/wiki/ISO_15924]script code[/url], in title case. + - [code]COUNTRY[/code] - 2 or 3-letter [url=https://en.wikipedia.org/wiki/ISO_3166-1]country code[/url], in upper case. + - [code]VARIANT[/code] - language variant, region and sort order. The variant can have any number of underscored keywords. + - [code]extra[/code] - semicolon separated list of additional key words. This may include currency, calendar, sort order and numbering system information. + If you want only the language code and not the fully specified locale from the OS, you can use [method get_locale_language]. </description> </method> <method name="get_locale_language" qualifiers="const"> @@ -280,11 +334,12 @@ <method name="get_memory_info" qualifiers="const"> <return type="Dictionary" /> <description> - Returns the [Dictionary] with the following keys: - [code]"physical"[/code] - total amount of usable physical memory, in bytes or [code]-1[/code] if unknown. This value can be slightly less than the actual physical memory amount, since it does not include memory reserved by kernel and devices. - [code]"free"[/code] - amount of physical memory, that can be immediately allocated without disk access or other costly operation, in bytes or [code]-1[/code] if unknown. The process might be able to allocate more physical memory, but such allocation will require moving inactive pages to disk and can take some time. - [code]"available"[/code] - amount of memory, that can be allocated without extending the swap file(s), in bytes or [code]-1[/code] if unknown. This value include both physical memory and swap. - [code]"stack"[/code] - size of the current thread stack, in bytes or [code]-1[/code] if unknown. + Returns a [Dictionary] containing information about the current memory with the following entries: + - [code]"physical"[/code] - total amount of usable physical memory in bytes. This value can be slightly less than the actual physical memory amount, since it does not include memory reserved by the kernel and devices. + - [code]"free"[/code] - amount of physical memory, that can be immediately allocated without disk access or other costly operations, in bytes. The process might be able to allocate more physical memory, but this action will require moving inactive pages to disk, which can be expensive. + - [code]"available"[/code] - amount of memory that can be allocated without extending the swap file(s), in bytes. This value includes both physical memory and swap. + - [code]"stack"[/code] - size of the current thread stack in bytes. + [b]Note:[/b] Each entry's value may be [code]-1[/code] if it is unknown. </description> </method> <method name="get_model_name" qualifiers="const"> @@ -297,65 +352,66 @@ <method name="get_name" qualifiers="const"> <return type="String" /> <description> - Returns the name of the host OS. - On Windows, this is [code]"Windows"[/code]. - On macOS, this is [code]"macOS"[/code]. - On Linux-based operating systems, this is [code]"Linux"[/code]. - On BSD-based operating systems, this is [code]"FreeBSD"[/code], [code]"NetBSD"[/code], [code]"OpenBSD"[/code], or [code]"BSD"[/code] as a fallback. - On Android, this is [code]"Android"[/code]. - On iOS, this is [code]"iOS"[/code]. - On the web, this is [code]"Web"[/code]. - [b]Note:[/b] Custom builds of the engine may support additional platforms, such as consoles, yielding other return values. + Returns the name of the host platform. + - On Windows, this is [code]"Windows"[/code]. + - On macOS, this is [code]"macOS"[/code]. + - On Linux-based operating systems, this is [code]"Linux"[/code]. + - On BSD-based operating systems, this is [code]"FreeBSD"[/code], [code]"NetBSD"[/code], [code]"OpenBSD"[/code], or [code]"BSD"[/code] as a fallback. + - On Android, this is [code]"Android"[/code]. + - On iOS, this is [code]"iOS"[/code]. + - On Web, this is [code]"Web"[/code]. + [b]Note:[/b] Custom builds of the engine may support additional platforms, such as consoles, possibly returning other names. [codeblocks] [gdscript] match OS.get_name(): "Windows": - print("Windows") + print("Welcome to Windows!") "macOS": - print("macOS") + print("Welcome to macOS!") "Linux", "FreeBSD", "NetBSD", "OpenBSD", "BSD": - print("Linux/BSD") + print("Welcome to Linux/BSD!") "Android": - print("Android") + print("Welcome to Android!") "iOS": - print("iOS") + print("Welcome to iOS!") "Web": - print("Web") + print("Welcome to the Web!") [/gdscript] [csharp] switch (OS.GetName()) { case "Windows": - GD.Print("Windows"); + GD.Print("Welcome to Windows"); break; case "macOS": - GD.Print("macOS"); + GD.Print("Welcome to macOS!"); break; case "Linux": case "FreeBSD": case "NetBSD": case "OpenBSD": case "BSD": - GD.Print("Linux/BSD"); + GD.Print("Welcome to Linux/BSD!"); break; case "Android": - GD.Print("Android"); + GD.Print("Welcome to Android!"); break; case "iOS": - GD.Print("iOS"); + GD.Print("Welcome to iOS!"); break; case "Web": - GD.Print("Web"); + GD.Print("Welcome to the Web!"); break; } [/csharp] [/codeblocks] + [b]Note:[/b] On Web platforms, it is still possible to determine the host platform's OS with feature tags. See [method has_feature]. </description> </method> <method name="get_process_id" qualifiers="const"> <return type="int" /> <description> - Returns the project's process ID. + Returns the number used by the host machine to uniquely identify this application. [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> @@ -368,7 +424,7 @@ <method name="get_processor_name" qualifiers="const"> <return type="String" /> <description> - Returns the name of the CPU model on the host machine (e.g. "Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz"). + Returns the full name of the CPU model on the host machine (e.g. [code]"Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz"[/code]). [b]Note:[/b] This method is only implemented on Windows, macOS, Linux and iOS. On Android and Web, [method get_processor_name] returns an empty string. </description> </method> @@ -381,13 +437,13 @@ <method name="get_static_memory_peak_usage" qualifiers="const"> <return type="int" /> <description> - Returns the maximum amount of static memory used (only works in debug). + Returns the maximum amount of static memory used. Only works in debug builds. </description> </method> <method name="get_static_memory_usage" qualifiers="const"> <return type="int" /> <description> - Returns the amount of static memory being used by the program in bytes (only works in debug). + Returns the amount of static memory being used by the program in bytes. Only works in debug builds. </description> </method> <method name="get_system_dir" qualifiers="const"> @@ -395,9 +451,9 @@ <param index="0" name="dir" type="int" enum="OS.SystemDir" /> <param index="1" name="shared_storage" type="bool" default="true" /> <description> - Returns the actual path to commonly used folders across different platforms. Available locations are specified in [enum SystemDir]. + Returns the path to commonly used folders across different platforms, as defined by [param dir]. See the [enum SystemDir] constants for available locations. [b]Note:[/b] This method is implemented on Android, Linux, macOS and Windows. - [b]Note:[/b] Shared storage is implemented on Android and allows to differentiate between app specific and shared directories. Shared directories have additional restrictions on Android. + [b]Note:[/b] Shared storage is implemented on Android and allows to differentiate between app specific and shared directories, if [param shared_storage] is [code]true[/code]. Shared directories have additional restrictions on Android. </description> </method> <method name="get_system_font_path" qualifiers="const"> @@ -407,7 +463,7 @@ <param index="2" name="stretch" type="int" default="100" /> <param index="3" name="italic" type="bool" default="false" /> <description> - Returns path to the system font file with [param font_name] and style. Returns empty string if no matching fonts found. + Returns the path to the system font file with [param font_name] and style. Returns an empty string if no matching fonts found. The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". [b]Note:[/b] Returned font might have different style if the requested style is not available. [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. @@ -423,7 +479,7 @@ <param index="5" name="stretch" type="int" default="100" /> <param index="6" name="italic" type="bool" default="false" /> <description> - Returns an array of the system substitute font file paths, which are similar to the font with [param font_name] and style for the specified text, locale and script. Returns empty array if no matching fonts found. + Returns an array of the system substitute font file paths, which are similar to the font with [param font_name] and style for the specified text, locale, and script. Returns an empty array if no matching fonts found. The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". [b]Note:[/b] Depending on OS, it's not guaranteed that any of the returned fonts will be suitable for rendering specified text. Fonts should be loaded and checked in the order they are returned, and the first suitable one used. [b]Note:[/b] Returned fonts might have different style if the requested style is not available or belong to a different font family. @@ -433,7 +489,7 @@ <method name="get_system_fonts" qualifiers="const"> <return type="PackedStringArray" /> <description> - Returns list of font family names available. + Returns the list of font family names available. [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> @@ -448,19 +504,19 @@ <return type="String" /> <description> Returns a string that is unique to the device. - [b]Note:[/b] This string may change without notice if the user reinstalls/upgrades their operating system or changes their hardware. This means it should generally not be used to encrypt persistent data as the data saved before an unexpected ID change would become inaccessible. The returned string may also be falsified using external programs, so do not rely on the string returned by [method get_unique_id] for security purposes. - [b]Note:[/b] Returns an empty string and prints an error on Web, as this method cannot be implemented on this platform. + [b]Note:[/b] This string may change without notice if the user reinstalls their operating system, upgrades it, or modifies their hardware. This means it should generally not be used to encrypt persistent data, as the data saved before an unexpected ID change would become inaccessible. The returned string may also be falsified using external programs, so do not rely on the string returned by this method for security purposes. + [b]Note:[/b] On Web, returns an empty string and generates an error, as this method cannot be implemented for security reasons. </description> </method> <method name="get_user_data_dir" qualifiers="const"> <return type="String" /> <description> - Returns the absolute directory path where user data is written ([code]user://[/code]). - On Windows, this is [code]%AppData%\Godot\app_userdata\[project_name][/code], or [code]%AppData%\[custom_name][/code] if [code]use_custom_user_dir[/code] is set. [code]%AppData%[/code] expands to [code]%UserProfile%\AppData\Roaming[/code]. - On macOS, this is [code]~/Library/Application Support/Godot/app_userdata/[project_name][/code], or [code]~/Library/Application Support/[custom_name][/code] if [code]use_custom_user_dir[/code] is set. - On Linux and BSD, this is [code]~/.local/share/godot/app_userdata/[project_name][/code], or [code]~/.local/share/[custom_name][/code] if [code]use_custom_user_dir[/code] is set. - On Android and iOS, this is a sandboxed directory in either internal or external storage, depending on the user's configuration. - On the web, this is a virtual directory managed by the browser. + Returns the absolute directory path where user data is written (the [code]user://[/code] directory in Godot). The path depends on the project name and [member ProjectSettings.application/config/use_custom_user_dir]. + - On Windows, this is [code]%AppData%\Godot\app_userdata\[project_name][/code], or [code]%AppData%\[custom_name][/code] if [code]use_custom_user_dir[/code] is set. [code]%AppData%[/code] expands to [code]%UserProfile%\AppData\Roaming[/code]. + - On macOS, this is [code]~/Library/Application Support/Godot/app_userdata/[project_name][/code], or [code]~/Library/Application Support/[custom_name][/code] if [code]use_custom_user_dir[/code] is set. + - On Linux and BSD, this is [code]~/.local/share/godot/app_userdata/[project_name][/code], or [code]~/.local/share/[custom_name][/code] if [code]use_custom_user_dir[/code] is set. + - On Android and iOS, this is a sandboxed directory in either internal or external storage, depending on the user's configuration. + - On Web, this is a virtual directory managed by the browser. If the project name is empty, [code][project_name][/code] falls back to [code][unnamed project][/code]. Not to be confused with [method get_data_dir], which returns the [i]global[/i] (non-project-specific) user home directory. </description> @@ -469,20 +525,20 @@ <return type="String" /> <description> Returns the exact production and build version of the operating system. This is different from the branded version used in marketing. This helps to distinguish between different releases of operating systems, including minor versions, and insider and custom builds. - For Windows, the major and minor version are returned, as well as the build number. For example, the returned string can look like [code]10.0.9926[/code] for a build of Windows 10, and it can look like [code]6.1.7601[/code] for a build of Windows 7 SP1. - For rolling distributions, such as Arch Linux, an empty string is returned. - For macOS and iOS, the major and minor version are returned, as well as the patch number. - For Android, the SDK version and the incremental build number are returned. If it's a custom ROM, it attempts to return its version instead. - [b]Note:[/b] This method is not supported on the web platform. It returns an empty string. + - For Windows, the major and minor version are returned, as well as the build number. For example, the returned string may look like [code]10.0.9926[/code] for a build of Windows 10, and it may look like [code]6.1.7601[/code] for a build of Windows 7 SP1. + - For rolling distributions, such as Arch Linux, an empty string is returned. + - For macOS and iOS, the major and minor version are returned, as well as the patch number. + - For Android, the SDK version and the incremental build number are returned. If it's a custom ROM, it attempts to return its version instead. + [b]Note:[/b] This method is not supported on the Web platform. It returns an empty string. </description> </method> <method name="get_video_adapter_driver_info" qualifiers="const"> <return type="PackedStringArray" /> <description> - Returns the video adapter driver name and version for the user's currently active graphics card. See also [method RenderingServer.get_video_adapter_api_version]. + Returns the video adapter driver name and version for the user's currently active graphics card, as a [PackedStringArray]. See also [method RenderingServer.get_video_adapter_api_version]. The first element holds the driver name, such as [code]nvidia[/code], [code]amdgpu[/code], etc. - The second element holds the driver version. For e.g. the [code]nvidia[/code] driver on a Linux/BSD platform, the version is in the format [code]510.85.02[/code]. For Windows, the driver's format is [code]31.0.15.1659[/code]. - [b]Note:[/b] This method is only supported on the platforms Linux/BSD and Windows when not running in headless mode. It returns an empty array on other platforms. + The second element holds the driver version. For example, on the [code]nvidia[/code] driver on a Linux/BSD platform, the version is in the format [code]510.85.02[/code]. For Windows, the driver's format is [code]31.0.15.1659[/code]. + [b]Note:[/b] This method is only supported on Linux/BSD and Windows when not running in headless mode. On other platforms, it returns an empty array. </description> </method> <method name="has_environment" qualifiers="const"> @@ -499,8 +555,7 @@ <description> Returns [code]true[/code] if the feature for the given feature tag is supported in the currently running instance, depending on the platform, build, etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the [url=$DOCS_URL/tutorials/export/feature_tags.html]Feature Tags[/url] documentation for more details. [b]Note:[/b] Tag names are case-sensitive. - [b]Note:[/b] On the web platform, one of the following additional tags is defined to indicate host platform: [code]web_android[/code], [code]web_ios[/code], [code]web_linuxbsd[/code], [code]web_macos[/code], or [code]web_windows[/code]. - [b]Note:[/b] On the iOS simulator, the additional [code]simulator[/code] tag is defined. + [b]Note:[/b] On the Web platform, one of the following additional tags is defined to indicate the host platform: [code]web_android[/code], [code]web_ios[/code], [code]web_linuxbsd[/code], [code]web_macos[/code], or [code]web_windows[/code]. </description> </method> <method name="is_debug_build" qualifiers="const"> @@ -508,22 +563,35 @@ <description> Returns [code]true[/code] if the Godot binary used to run the project is a [i]debug[/i] export template, or when running in the editor. Returns [code]false[/code] if the Godot binary used to run the project is a [i]release[/i] export template. - To check whether the Godot binary used to run the project is an export template (debug or release), use [code]OS.has_feature("template")[/code] instead. + [b]Note:[/b] To check whether the Godot binary used to run the project is an export template (debug or release), use [code]OS.has_feature("template")[/code] instead. </description> </method> <method name="is_keycode_unicode" qualifiers="const"> <return type="bool" /> <param index="0" name="code" type="int" /> <description> - Returns [code]true[/code] if the input keycode corresponds to a Unicode character. + Returns [code]true[/code] if the input keycode corresponds to a Unicode character. For a list of codes, see the [enum Key] constants. + [codeblocks] + [gdscript] + print(OS.is_keycode_unicode(KEY_G)) # Prints true + print(OS.is_keycode_unicode(KEY_KP_4)) # Prints true + print(OS.is_keycode_unicode(KEY_TAB)) # Prints false + print(OS.is_keycode_unicode(KEY_ESCAPE)) # Prints false + [/gdscript] + [csharp] + GD.Print(OS.IsKeycodeUnicode((long)Key.G)); // Prints true + GD.Print(OS.IsKeycodeUnicode((long)Key.Kp4)); // Prints true + GD.Print(OS.IsKeycodeUnicode((long)Key.Tab)); // Prints false + GD.Print(OS.IsKeycodeUnicode((long)Key.Escape)); // Prints false + [/csharp] + [/codeblocks] </description> </method> <method name="is_process_running" qualifiers="const"> <return type="bool" /> <param index="0" name="pid" type="int" /> <description> - Returns [code]true[/code] if the child process ID ([param pid]) is still running or [code]false[/code] if it has terminated. - Must be a valid ID generated from [method create_process]. + Returns [code]true[/code] if the child process ID ([param pid]) is still running or [code]false[/code] if it has terminated. [param pid] must be a valid ID generated from [method create_process]. [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> @@ -536,8 +604,8 @@ <method name="is_sandboxed" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if application is running in the sandbox. - [b]Note:[/b] This method is implemented on macOS and Linux. + Returns [code]true[/code] if the application is running in the sandbox. + [b]Note:[/b] This method is only implemented on macOS and Linux. </description> </method> <method name="is_stdout_verbose" qualifiers="const"> @@ -549,15 +617,15 @@ <method name="is_userfs_persistent" qualifiers="const"> <return type="bool" /> <description> - If [code]true[/code], the [code]user://[/code] file system is persistent, so that its state is the same after a player quits and starts the game again. Relevant to the Web platform, where this persistence may be unavailable. + Returns [code]true[/code] if the [code]user://[/code] file system is persistent, that is, its state is the same after a player quits and starts the game again. Relevant to the Web platform, where this persistence may be unavailable. </description> </method> <method name="kill"> <return type="int" enum="Error" /> <param index="0" name="pid" type="int" /> <description> - Kill (terminate) the process identified by the given process ID ([param pid]), e.g. the one returned by [method execute] in non-blocking mode. See also [method crash]. - [b]Note:[/b] This method can also be used to kill processes that were not spawned by the game. + Kill (terminate) the process identified by the given process ID ([param pid]), such as the ID returned by [method execute] in non-blocking mode. See also [method crash]. + [b]Note:[/b] This method can also be used to kill processes that were not spawned by the engine. [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> @@ -565,9 +633,9 @@ <return type="int" enum="Error" /> <param index="0" name="path" type="String" /> <description> - Moves the file or directory to the system's recycle bin. See also [method DirAccess.remove]. + Moves the file or directory at the given [param path] to the system's recycle bin. See also [method DirAccess.remove]. The method takes only global paths, so you may need to use [method ProjectSettings.globalize_path]. Do not use it for files in [code]res://[/code] as it will not work in exported projects. - [b]Note:[/b] If the user has disabled the recycle bin on their system, the file will be permanently deleted instead. + Returns [constant FAILED] if the file or directory cannot be found, or the system does not support this method. [codeblocks] [gdscript] var file_to_remove = "user://slot1.save" @@ -578,12 +646,14 @@ OS.MoveToTrash(ProjectSettings.GlobalizePath(fileToRemove)); [/csharp] [/codeblocks] + [b]Note:[/b] This method is implemented on Android, Linux, macOS and Windows. + [b]Note:[/b] If the user has disabled the recycle bin on their system, the file will be permanently deleted instead. </description> </method> <method name="open_midi_inputs"> <return type="void" /> <description> - Initializes the singleton for the system MIDI driver. + Initializes the singleton for the system MIDI driver, allowing Godot to receive [InputEventMIDI]. See also [method get_connected_midi_inputs] and [method close_midi_inputs]. [b]Note:[/b] This method is implemented on Linux, macOS and Windows. </description> </method> @@ -592,20 +662,22 @@ <description> Reads a user input string from the standard input (usually the terminal). This operation is [i]blocking[/i], which causes the window to freeze if [method read_string_from_stdin] is called on the main thread. The thread calling [method read_string_from_stdin] will block until the program receives a line break in standard input (usually by the user pressing [kbd]Enter[/kbd]). [b]Note:[/b] This method is implemented on Linux, macOS and Windows. + [b]Note:[/b] On exported Windows builds, run the console wrapper executable to access the terminal. Otherwise, the standard input will not work correctly. If you need a single executable with console support, use a custom build compiled with the [code]windows_subsystem=console[/code] flag. </description> </method> <method name="request_permission"> <return type="bool" /> <param index="0" name="name" type="String" /> <description> - At the moment this function is only used by [code]AudioDriverOpenSL[/code] to request permission for [code]RECORD_AUDIO[/code] on Android. + Requests permission from the OS for the given [param name]. Returns [code]true[/code] if the permission has been successfully granted. + [b]Note:[/b] This method is currently only implemented on Android, to specifically request permission for [code]"RECORD_AUDIO"[/code] by [code]AudioDriverOpenSL[/code]. </description> </method> <method name="request_permissions"> <return type="bool" /> <description> - With this function, you can request dangerous permissions since normal permissions are automatically granted at install time in Android applications. - [b]Note:[/b] This method is implemented only on Android. + Requests [i]dangerous[/i] permissions from the OS. Returns [code]true[/code] if permissions have been successfully granted. + [b]Note:[/b] This method is only implemented on Android. Normal permissions are automatically granted at install time in Android applications. </description> </method> <method name="revoke_granted_permissions"> @@ -628,8 +700,8 @@ <param index="0" name="restart" type="bool" /> <param index="1" name="arguments" type="PackedStringArray" default="PackedStringArray()" /> <description> - If [param restart] is [code]true[/code], restarts the project automatically when it is exited with [method SceneTree.quit] or [constant Node.NOTIFICATION_WM_CLOSE_REQUEST]. Command line [param arguments] can be supplied. To restart the project with the same command line arguments as originally used to run the project, pass [method get_cmdline_args] as the value for [param arguments]. - [method set_restart_on_exit] can be used to apply setting changes that require a restart. See also [method is_restart_on_exit_set] and [method get_restart_on_exit_arguments]. + If [param restart] is [code]true[/code], restarts the project automatically when it is exited with [method SceneTree.quit] or [constant Node.NOTIFICATION_WM_CLOSE_REQUEST]. Command-line [param arguments] can be supplied. To restart the project with the same command line arguments as originally used to run the project, pass [method get_cmdline_args] as the value for [param arguments]. + This method can be used to apply setting changes that require a restart. See also [method is_restart_on_exit_set] and [method get_restart_on_exit_arguments]. [b]Note:[/b] This method is only effective on desktop platforms, and only when the project isn't started from the editor. It will have no effect on mobile and Web platforms, or when the project is started from the editor. [b]Note:[/b] If the project process crashes or is [i]killed[/i] by the user (by sending [code]SIGKILL[/code] instead of the usual [code]SIGTERM[/code]), the project won't restart automatically. </description> @@ -638,25 +710,26 @@ <return type="int" enum="Error" /> <param index="0" name="name" type="String" /> <description> - Sets the name of the current thread. + Assigns the given name to the current thread. Returns [constant ERR_UNAVAILABLE] if unavailable on the current platform. </description> </method> <method name="set_use_file_access_save_and_swap"> <return type="void" /> <param index="0" name="enabled" type="bool" /> <description> - Enables backup saves if [param enabled] is [code]true[/code]. + If [param enabled] is [code]true[/code], when opening a file for writing, a temporary file is used in its place. When closed, it is automatically applied to the target file. + This can useful when files may be opened by other applications, such as antiviruses, text editors, or even the Godot editor itself. </description> </method> <method name="shell_open"> <return type="int" enum="Error" /> <param index="0" name="uri" type="String" /> <description> - Requests the OS to open a resource with the most appropriate program. For example: + Requests the OS to open a resource identified by [param uri] with the most appropriate program. For example: - [code]OS.shell_open("C:\\Users\name\Downloads")[/code] on Windows opens the file explorer at the user's Downloads folder. - [code]OS.shell_open("https://godotengine.org")[/code] opens the default web browser on the official Godot website. - [code]OS.shell_open("mailto:example@example.com")[/code] opens the default email client with the "To" field set to [code]example@example.com[/code]. See [url=https://datatracker.ietf.org/doc/html/rfc2368]RFC 2368 - The [code]mailto[/code] URL scheme[/url] for a list of fields that can be added. - Use [method ProjectSettings.globalize_path] to convert a [code]res://[/code] or [code]user://[/code] path into a system path for use with this method. + Use [method ProjectSettings.globalize_path] to convert a [code]res://[/code] or [code]user://[/code] project path into a system path for use with this method. [b]Note:[/b] Use [method String.uri_encode] to encode characters within URLs in a URL-safe, portable way. This is especially required for line breaks. Otherwise, [method shell_open] may not work correctly in a project exported to the Web platform. [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux, macOS and Windows. </description> @@ -666,30 +739,33 @@ <param index="0" name="file_or_dir_path" type="String" /> <param index="1" name="open_folder" type="bool" default="true" /> <description> - Requests the OS to open the file manager, then navigate to the given [param file_or_dir_path] and select the target file or folder. - If [param file_or_dir_path] is a valid directory path, and [param open_folder] is [code]true[/code], the method will open the file manager and enter the target folder without selecting anything. - Use [method ProjectSettings.globalize_path] to convert a [code]res://[/code] or [code]user://[/code] path into a system path for use with this method. - [b]Note:[/b] Currently this method is only implemented on Windows and macOS. On other platforms, it will fallback to [method shell_open] with a directory path of [param file_or_dir_path] with prefix [code]file://[/code]. + Requests the OS to open the file manager, navigate to the given [param file_or_dir_path] and select the target file or folder. + If [param open_folder] is [code]true[/code] and [param file_or_dir_path] is a valid directory path, the OS will open the file manager and navigate to the target folder without selecting anything. + Use [method ProjectSettings.globalize_path] to convert a [code]res://[/code] or [code]user://[/code] project path into a system path to use with this method. + [b]Note:[/b] This method is currently only implemented on Windows and macOS. On other platforms, it will fallback to [method shell_open] with a directory path of [param file_or_dir_path] prefixed with [code]file://[/code]. </description> </method> <method name="unset_environment" qualifiers="const"> <return type="void" /> <param index="0" name="variable" type="String" /> <description> - Removes the environment [param variable] from the current environment, if it exists. The environment variable will be removed for the Godot process and any process executed with [method execute] after running [method unset_environment]. The removal of the environment variable will [i]not[/i] persist to processes run after the Godot process was terminated. - [b]Note:[/b] Environment variable names are case-sensitive on all platforms except Windows. The [param variable] name cannot be empty or include the [code]=[/code] character. + Removes the given environment variable from the current environment, if it exists. The [param variable] name cannot be empty or include the [code]=[/code] character. The environment variable will be removed for the Godot process and any process executed with [method execute] after running [method unset_environment]. The removal of the environment variable will [i]not[/i] persist to processes run after the Godot process was terminated. + [b]Note:[/b] Environment variable names are case-sensitive on all platforms except Windows. </description> </method> </methods> <members> <member name="delta_smoothing" type="bool" setter="set_delta_smoothing" getter="is_delta_smoothing_enabled" default="true"> - If [code]true[/code], the engine filters the time delta measured between each frame, and attempts to compensate for random variation. This will only operate on systems where V-Sync is active. + If [code]true[/code], the engine filters the time delta measured between each frame, and attempts to compensate for random variation. This only works on systems where V-Sync is active. + [b]Note:[/b] On start-up, this is the same as [member ProjectSettings.application/run/delta_smoothing]. </member> <member name="low_processor_usage_mode" type="bool" setter="set_low_processor_usage_mode" getter="is_in_low_processor_usage_mode" default="false"> If [code]true[/code], the engine optimizes for low processor usage by only refreshing the screen if needed. Can improve battery consumption on mobile. + [b]Note:[/b] On start-up, this is the same as [member ProjectSettings.application/run/low_processor_mode]. </member> <member name="low_processor_usage_mode_sleep_usec" type="int" setter="set_low_processor_usage_mode_sleep_usec" getter="get_low_processor_usage_mode_sleep_usec" default="6900"> - The amount of sleeping between frames when the low-processor usage mode is enabled (in microseconds). Higher values will result in lower CPU usage. + The amount of sleeping between frames when the low-processor usage mode is enabled, in microseconds. Higher values will result in lower CPU usage. See also [member low_processor_usage_mode]. + [b]Note:[/b] On start-up, this is the same as [member ProjectSettings.application/run/low_processor_mode_sleep_usec]. </member> </members> <constants> @@ -699,29 +775,32 @@ <constant name="RENDERING_DRIVER_OPENGL3" value="1" enum="RenderingDriver"> The OpenGL 3 rendering driver. It uses OpenGL 3.3 Core Profile on desktop platforms, OpenGL ES 3.0 on mobile devices, and WebGL 2.0 on Web. </constant> + <constant name="RENDERING_DRIVER_D3D12" value="2" enum="RenderingDriver"> + The Direct3D 12 rendering driver. + </constant> <constant name="SYSTEM_DIR_DESKTOP" value="0" enum="SystemDir"> - Desktop directory path. + Refers to the Desktop directory path. </constant> <constant name="SYSTEM_DIR_DCIM" value="1" enum="SystemDir"> - DCIM (Digital Camera Images) directory path. + Refers to the DCIM (Digital Camera Images) directory path. </constant> <constant name="SYSTEM_DIR_DOCUMENTS" value="2" enum="SystemDir"> - Documents directory path. + Refers to the Documents directory path. </constant> <constant name="SYSTEM_DIR_DOWNLOADS" value="3" enum="SystemDir"> - Downloads directory path. + Refers to the Downloads directory path. </constant> <constant name="SYSTEM_DIR_MOVIES" value="4" enum="SystemDir"> - Movies directory path. + Refers to the Movies (or Videos) directory path. </constant> <constant name="SYSTEM_DIR_MUSIC" value="5" enum="SystemDir"> - Music directory path. + Refers to the Music directory path. </constant> <constant name="SYSTEM_DIR_PICTURES" value="6" enum="SystemDir"> - Pictures directory path. + Refers to the Pictures directory path. </constant> <constant name="SYSTEM_DIR_RINGTONES" value="7" enum="SystemDir"> - Ringtones directory path. + Refers to the Ringtones directory path. </constant> </constants> </class> diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index 2ffb02096d..b69326b6e0 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -76,83 +76,112 @@ <method name="_get_property_list" qualifiers="virtual"> <return type="Dictionary[]" /> <description> - Override this method to customize how script properties should be handled by the engine. + Override this method to provide a custom list of additional properties to handle by the engine. Should return a property list, as an [Array] of dictionaries. The result is added to the array of [method get_property_list], and should be formatted in the same way. Each [Dictionary] must at least contain the [code]name[/code] and [code]type[/code] entries. - The example below displays [code]hammer_type[/code] in the Inspector dock, only if [code]holding_hammer[/code] is [code]true[/code]: + You can use [method _property_can_revert] and [method _property_get_revert] to customize the default values of the properties added by this method. + The example below displays a list of numbers shown as words going from [code]ZERO[/code] to [code]FIVE[/code], with [code]number_count[/code] controlling the size of the list: [codeblocks] [gdscript] @tool - extends Node2D + extends Node - @export var holding_hammer = false: - set(value): - holding_hammer = value + @export var number_count = 3: + set(nc): + number_count = nc + numbers.resize(number_count) notify_property_list_changed() - var hammer_type = 0 - func _get_property_list(): - # By default, `hammer_type` is not visible in the editor. - var property_usage = PROPERTY_USAGE_NO_EDITOR - - if holding_hammer: - property_usage = PROPERTY_USAGE_DEFAULT + var numbers = PackedInt32Array([0, 0, 0]) + func _get_property_list(): var properties = [] - properties.append({ - "name": "hammer_type", - "type": TYPE_INT, - "usage": property_usage, # See above assignment. - "hint": PROPERTY_HINT_ENUM, - "hint_string": "Wooden,Iron,Golden,Enchanted" - }) + + for i in range(number_count): + properties.append({ + "name": "number_%d" % i, + "type": TYPE_INT, + "hint": PROPERTY_HINT_ENUM, + "hint_string": "ZERO,ONE,TWO,THREE,FOUR,FIVE", + }) return properties + + func _get(property): + if property.begins_with("number_"): + var index = property.get_slice("_", 1).to_int() + return numbers[index] + + func _set(property, value): + if property.begins_with("number_"): + var index = property.get_slice("_", 1).to_int() + numbers[index] = value + return true + return false [/gdscript] [csharp] [Tool] - public partial class MyNode2D : Node2D + public partial class MyNode : Node { - private bool _holdingHammer; + private int _numberCount; [Export] - public bool HoldingHammer + public int NumberCount { - get => _holdingHammer; + get => _numberCount; set { - _holdingHammer = value; + _numberCount = value; + _numbers.Resize(_numberCount); NotifyPropertyListChanged(); } } - public int HammerType { get; set; } + private List<int> _numbers = new(); public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList() { - // By default, `HammerType` is not visible in the editor. - var propertyUsage = PropertyUsageFlags.NoEditor; + var properties = new Godot.Collections.Array<Godot.Collections.Dictionary>(); - if (HoldingHammer) + for (int i = 0; i < _numberCount; i++) { - propertyUsage = PropertyUsageFlags.Default; + properties.Add(new Godot.Collections.Dictionary() + { + { "name", $"number_{i}" }, + { "type", (int)Variant.Type.Int }, + { "hint", (int)PropertyHint.Enum }, + { "hint_string", "Zero,One,Two,Three,Four,Five" }, + }); } - var properties = new Godot.Collections.Array<Godot.Collections.Dictionary>(); - properties.Add(new Godot.Collections.Dictionary() + return properties; + } + + public override Variant _Get(StringName property) + { + string propertyName = property.ToString(); + if (propertyName.StartsWith("number_")) { - { "name", "HammerType" }, - { "type", (int)Variant.Type.Int }, - { "usage", (int)propertyUsage }, // See above assignment. - { "hint", (int)PropertyHint.Enum }, - { "hint_string", "Wooden,Iron,Golden,Enchanted" } - }); + int index = int.Parse(propertyName.Substring("number_".Length)); + return _numbers[index]; + } + return default; + } - return properties; + public override bool _Set(StringName property, Variant value) + { + string propertyName = property.ToString(); + if (propertyName.StartsWith("number_")) + { + int index = int.Parse(propertyName.Substring("number_".Length)); + numbers[index] = value.As<int>(); + return true; + } + return false; } } [/csharp] [/codeblocks] - [b]Note:[/b] This method is intended for advanced purposes. For most common use cases, the scripting languages offer easier ways to handle properties. See [annotation @GDScript.@export], [annotation @GDScript.@export_enum], [annotation @GDScript.@export_group], etc. + [b]Note:[/b] This method is intended for advanced purposes. For most common use cases, the scripting languages offer easier ways to handle properties. See [annotation @GDScript.@export], [annotation @GDScript.@export_enum], [annotation @GDScript.@export_group], etc. If you want to customize exported properties, use [method _validate_property]. [b]Note:[/b] If the object's script is not [annotation @GDScript.@tool], this method will not be called in the editor. </description> </method> @@ -191,7 +220,7 @@ <return type="bool" /> <param index="0" name="property" type="StringName" /> <description> - Override this method to customize the given [param property]'s revert behavior. Should return [code]true[/code] if the [param property] can be reverted in the Inspector dock. Use [method _property_get_revert] to specify the [param property]'s default value. + Override this method to customize the given [param property]'s revert behavior. Should return [code]true[/code] if the [param property] has a custom default value and is revertible in the Inspector dock. Use [method _property_get_revert] to specify the [param property]'s default value. [b]Note:[/b] This method must return consistently, regardless of the current value of the [param property]. </description> </method> @@ -274,7 +303,7 @@ <return type="void" /> <param index="0" name="property" type="Dictionary" /> <description> - Override this method to customize existing properties. Every property info goes through this method. The dictionary contents is the same as in [method _get_property_list]. + Override this method to customize existing properties. Every property info goes through this method, except properties added with [method _get_property_list]. The dictionary contents is the same as in [method _get_property_list]. [codeblocks] [gdscript] @tool @@ -314,7 +343,7 @@ { if (property["name"].AsStringName() == PropertyName.Number && IsNumberEditable) { - var usage = property["usage"].As>PropertyUsageFlags<() | PropertyUsageFlags.ReadOnly; + var usage = property["usage"].As<PropertyUsageFlags>() | PropertyUsageFlags.ReadOnly; property["usage"] = (int)usage; } } @@ -377,7 +406,7 @@ <param index="0" name="method" type="StringName" /> <description> Calls the [param method] on the object during idle time. Always returns null, [b]not[/b] the method's result. - 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. If not done carefully, this can result in infinite recursion without causing a stack overflow, which will hang the game similarly to an infinite loop. + 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. This method supports a variable number of arguments, so parameters can be passed as a comma separated list. [codeblocks] [gdscript] @@ -594,7 +623,7 @@ [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> - <method name="free"> + <method name="free" keywords="delete, remove, kill, die"> <return type="void" /> <description> Deletes the object from memory. Pre-existing references to the object become invalid, and any attempt to access them will result in a run-time error. Checking the references with [method @GlobalScope.is_instance_valid] will return [code]false[/code]. @@ -614,7 +643,7 @@ [csharp] var node = new Node2D(); node.Rotation = 1.5f; - var a = node.Get("rotation"); // a is 1.5 + var a = node.Get(Node2D.PropertyName.Rotation); // a is 1.5 [/csharp] [/codeblocks] [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. @@ -682,6 +711,14 @@ Returns the object's metadata entry names as a [PackedStringArray]. </description> </method> + <method name="get_method_argument_count" qualifiers="const"> + <return type="int" /> + <param index="0" name="method" type="StringName" /> + <description> + Returns the number of arguments of the given [param method] by name. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. + </description> + </method> <method name="get_method_list" qualifiers="const"> <return type="Dictionary[]" /> <description> @@ -882,7 +919,7 @@ [/gdscript] [csharp] var node = new Node2D(); - node.Set("global_scale", new Vector2(8, 2.5)); + node.Set(Node2D.PropertyName.GlobalScale, new Vector2(8, 2.5)); GD.Print(node.GlobalScale); // Prints Vector2(8, 2.5) [/csharp] [/codeblocks] @@ -907,21 +944,21 @@ var node = Node2D.new() add_child(node) - node.rotation = 45.0 - node.set_deferred("rotation", 90.0) - print(node.rotation) # Prints 45.0 + node.rotation = 1.5 + node.set_deferred("rotation", 3.0) + print(node.rotation) # Prints 1.5 await get_tree().process_frame - print(node.rotation) # Prints 90.0 + print(node.rotation) # Prints 3.0 [/gdscript] [csharp] var node = new Node2D(); - node.Rotation = 45f; - node.SetDeferred("rotation", 90f); - GD.Print(node.Rotation); // Prints 45.0 + node.Rotation = 1.5f; + node.SetDeferred(Node2D.PropertyName.Rotation, 3f); + GD.Print(node.Rotation); // Prints 1.5 await ToSignal(GetTree(), SceneTree.SignalName.ProcessFrame); - GD.Print(node.Rotation); // Prints 90.0 + GD.Print(node.Rotation); // Prints 3.0 [/csharp] [/codeblocks] [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. @@ -985,9 +1022,9 @@ <method name="tr" qualifiers="const"> <return type="String" /> <param index="0" name="message" type="StringName" /> - <param index="1" name="context" type="StringName" default="""" /> + <param index="1" name="context" type="StringName" default="&""" /> <description> - Translates a [param message], using the translation catalogs configured in the Project Settings. Further [param context] can be specified to help with the translation. + Translates a [param message], using the translation catalogs configured in the Project Settings. Further [param context] can be specified to help with the translation. Note that most [Control] nodes automatically translate their strings, so this method is mostly useful for formatted strings or custom drawn text. If [method can_translate_messages] is [code]false[/code], or no translation is available, this method returns the [param message] without changes. See [method set_message_translation]. For detailed examples, see [url=$DOCS_URL/tutorials/i18n/internationalizing_games.html]Internationalizing games[/url]. </description> @@ -997,13 +1034,13 @@ <param index="0" name="message" type="StringName" /> <param index="1" name="plural_message" type="StringName" /> <param index="2" name="n" type="int" /> - <param index="3" name="context" type="StringName" default="""" /> + <param index="3" name="context" type="StringName" default="&""" /> <description> Translates a [param message] or [param plural_message], using the translation catalogs configured in the Project Settings. Further [param context] can be specified to help with the translation. If [method can_translate_messages] is [code]false[/code], or no translation is available, this method returns [param message] or [param plural_message], without changes. See [method set_message_translation]. The [param n] is the number, or amount, of the message's subject. It is used by the translation system to fetch the correct plural form for the current language. For detailed examples, see [url=$DOCS_URL/tutorials/i18n/localization_using_gettext.html]Localization using gettext[/url]. - [b]Note:[/b] Negative and [float] numbers may not properly apply to some countable subjects. It's recommended handling these cases with [method tr]. + [b]Note:[/b] Negative and [float] numbers may not properly apply to some countable subjects. It's recommended to handle these cases with [method tr]. </description> </method> </methods> @@ -1027,6 +1064,9 @@ <constant name="NOTIFICATION_PREDELETE" value="1"> Notification received when the object is about to be deleted. Can act as the deconstructor of some programming languages. </constant> + <constant name="NOTIFICATION_EXTENSION_RELOADED" value="2"> + Notification received when the object finishes hot reloading. This notification is only sent for extensions classes and derived. + </constant> <constant name="CONNECT_DEFERRED" value="1" enum="ConnectFlags"> Deferred connections trigger their [Callable]s on idle time (at the end of the frame), rather than instantly. </constant> diff --git a/doc/classes/OmniLight3D.xml b/doc/classes/OmniLight3D.xml index f8de34e159..64bf981a90 100644 --- a/doc/classes/OmniLight3D.xml +++ b/doc/classes/OmniLight3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="OmniLight3D" inherits="Light3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="OmniLight3D" inherits="Light3D" keywords="point" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Omnidirectional light, such as a light bulb or a candle. </brief_description> @@ -14,8 +14,10 @@ </tutorials> <members> <member name="omni_attenuation" type="float" setter="set_param" getter="get_param" default="1.0"> - The light's attenuation (drop-off) curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. Zero and negative values are allowed but can produce unusual effects. - [b]Note:[/b] Very high [member omni_attenuation] values (typically above 10) can impact performance negatively if the light is made to use a larger [member omni_range] to compensate. This is because culling opportunities will become less common and shading costs will be increased (as the light will cover more pixels on screen while resulting in the same amount of brightness). To improve performance, use the lowest [member omni_attenuation] value possible for the visuals you're trying to achieve. + Controls the distance attenuation function for omnilights. + A value of [code]0.0[/code] smoothly attenuates light at the edge of the range. A value of [code]1.0[/code] approaches a physical lighting model. A value of [code]0.5[/code] approximates linear attenuation. + [b]Note:[/b] Setting it to [code]1.0[/code] may result in distant objects receiving minimal light, even within range. For example, with a range of [code]4096[/code], an object at [code]100[/code] units receives less than [code]0.1[/code] energy. + [b]Note:[/b] Using negative or values higher than [code]10.0[/code] may lead to unexpected results. </member> <member name="omni_range" type="float" setter="set_param" getter="get_param" default="5.0"> The light's radius. Note that the effectively lit area may appear to be smaller depending on the [member omni_attenuation] in use. No matter the [member omni_attenuation] in use, the light will never reach anything outside this radius. diff --git a/doc/classes/OptionButton.xml b/doc/classes/OptionButton.xml index 4e223c12fa..f04b0d942f 100644 --- a/doc/classes/OptionButton.xml +++ b/doc/classes/OptionButton.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="OptionButton" inherits="Button" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="OptionButton" inherits="Button" keywords="select" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A button that brings up a dropdown with selectable options when pressed. </brief_description> diff --git a/doc/classes/PCKPacker.xml b/doc/classes/PCKPacker.xml index 2627c8b7d3..494e9966ac 100644 --- a/doc/classes/PCKPacker.xml +++ b/doc/classes/PCKPacker.xml @@ -13,7 +13,7 @@ packer.flush() [/gdscript] [csharp] - var packer = new PCKPacker(); + var packer = new PckPacker(); packer.PckStart("test.pck"); packer.AddFile("res://text.txt", "text.txt"); packer.Flush(); diff --git a/doc/classes/PackedByteArray.xml b/doc/classes/PackedByteArray.xml index 516cc9f020..0c1532f61a 100644 --- a/doc/classes/PackedByteArray.xml +++ b/doc/classes/PackedByteArray.xml @@ -79,21 +79,21 @@ <return type="float" /> <param index="0" name="byte_offset" type="int" /> <description> - Decodes a 64-bit floating point number from the bytes starting at [param byte_offset]. Fails if the byte count is insufficient. Returns [code]0.0[/code] if a valid number can't be decoded. + Decodes a 64-bit floating-point number from the bytes starting at [param byte_offset]. Fails if the byte count is insufficient. Returns [code]0.0[/code] if a valid number can't be decoded. </description> </method> <method name="decode_float" qualifiers="const"> <return type="float" /> <param index="0" name="byte_offset" type="int" /> <description> - Decodes a 32-bit floating point number from the bytes starting at [param byte_offset]. Fails if the byte count is insufficient. Returns [code]0.0[/code] if a valid number can't be decoded. + Decodes a 32-bit floating-point number from the bytes starting at [param byte_offset]. Fails if the byte count is insufficient. Returns [code]0.0[/code] if a valid number can't be decoded. </description> </method> <method name="decode_half" qualifiers="const"> <return type="float" /> <param index="0" name="byte_offset" type="int" /> <description> - Decodes a 16-bit floating point number from the bytes starting at [param byte_offset]. Fails if the byte count is insufficient. Returns [code]0.0[/code] if a valid number can't be decoded. + Decodes a 16-bit floating-point number from the bytes starting at [param byte_offset]. Fails if the byte count is insufficient. Returns [code]0.0[/code] if a valid number can't be decoded. </description> </method> <method name="decode_s8" qualifiers="const"> @@ -174,6 +174,7 @@ <param index="1" name="compression_mode" type="int" default="0" /> <description> Returns a new [PackedByteArray] with the data decompressed. Set [param buffer_size] to the size of the uncompressed data. Set the compression mode using one of [enum FileAccess.CompressionMode]'s constants. + [b]Note:[/b] Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header. </description> </method> <method name="decompress_dynamic" qualifiers="const"> @@ -184,6 +185,7 @@ Returns a new [PackedByteArray] with the data decompressed. Set the compression mode using one of [enum FileAccess.CompressionMode]'s constants. [b]This method only accepts brotli, gzip, and deflate compression modes.[/b] This method is potentially slower than [method decompress], as it may have to re-allocate its output buffer multiple times while decompressing, whereas [method decompress] knows it's output buffer size from the beginning. GZIP has a maximal compression ratio of 1032:1, meaning it's very possible for a small compressed payload to decompress to a potentially very large output. To guard against this, you may provide a maximum size this function is allowed to allocate in bytes via [param max_output_size]. Passing -1 will allow for unbounded output. If any positive value is passed, and the decompression exceeds that amount in bytes, then an error will be returned. + [b]Note:[/b] Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header. </description> </method> <method name="duplicate"> @@ -197,7 +199,7 @@ <param index="0" name="byte_offset" type="int" /> <param index="1" name="value" type="float" /> <description> - Encodes a 64-bit floating point number as bytes at the index of [param byte_offset] bytes. The array must have at least 8 bytes of allocated space, starting at the offset. + Encodes a 64-bit floating-point number as bytes at the index of [param byte_offset] bytes. The array must have at least 8 bytes of allocated space, starting at the offset. </description> </method> <method name="encode_float"> @@ -205,7 +207,7 @@ <param index="0" name="byte_offset" type="int" /> <param index="1" name="value" type="float" /> <description> - Encodes a 32-bit floating point number as bytes at the index of [param byte_offset] bytes. The array must have at least 4 bytes of space, starting at the offset. + Encodes a 32-bit floating-point number as bytes at the index of [param byte_offset] bytes. The array must have at least 4 bytes of space, starting at the offset. </description> </method> <method name="encode_half"> @@ -213,7 +215,7 @@ <param index="0" name="byte_offset" type="int" /> <param index="1" name="value" type="float" /> <description> - Encodes a 16-bit floating point number as bytes at the index of [param byte_offset] bytes. The array must have at least 2 bytes of space, starting at the offset. + Encodes a 16-bit floating-point number as bytes at the index of [param byte_offset] bytes. The array must have at least 2 bytes of space, starting at the offset. </description> </method> <method name="encode_s8"> @@ -397,7 +399,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedColorArray.xml b/doc/classes/PackedColorArray.xml index dc6238b268..c2156e511f 100644 --- a/doc/classes/PackedColorArray.xml +++ b/doc/classes/PackedColorArray.xml @@ -132,7 +132,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedFloat32Array.xml b/doc/classes/PackedFloat32Array.xml index 56f9633533..6f1ecacca4 100644 --- a/doc/classes/PackedFloat32Array.xml +++ b/doc/classes/PackedFloat32Array.xml @@ -132,7 +132,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedFloat64Array.xml b/doc/classes/PackedFloat64Array.xml index cc820f3ee1..9b62df2ada 100644 --- a/doc/classes/PackedFloat64Array.xml +++ b/doc/classes/PackedFloat64Array.xml @@ -133,7 +133,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedInt32Array.xml b/doc/classes/PackedInt32Array.xml index c70cadc2fe..e6396e2a93 100644 --- a/doc/classes/PackedInt32Array.xml +++ b/doc/classes/PackedInt32Array.xml @@ -128,7 +128,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedInt64Array.xml b/doc/classes/PackedInt64Array.xml index 97948d4b32..cbbcdb12d7 100644 --- a/doc/classes/PackedInt64Array.xml +++ b/doc/classes/PackedInt64Array.xml @@ -129,7 +129,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedScene.xml b/doc/classes/PackedScene.xml index a8cfc288f3..9324f99535 100644 --- a/doc/classes/PackedScene.xml +++ b/doc/classes/PackedScene.xml @@ -88,7 +88,7 @@ Returns the [SceneState] representing the scene file contents. </description> </method> - <method name="instantiate" qualifiers="const"> + <method name="instantiate" qualifiers="const" keywords="create, make, spawn, new"> <return type="Node" /> <param index="0" name="edit_state" type="int" enum="PackedScene.GenEditState" default="0" /> <description> @@ -106,7 +106,7 @@ <members> <member name="_bundled" type="Dictionary" setter="_set_bundled_scene" getter="_get_bundled_scene" default="{ "conn_count": 0, "conns": PackedInt32Array(), "editable_instances": [], "names": PackedStringArray(), "node_count": 0, "node_paths": [], "nodes": PackedInt32Array(), "variants": [], "version": 3 }"> A dictionary representation of the scene contents. - Available keys include "rnames" and "variants" for resources, "node_count", "nodes", "node_paths" for nodes, "editable_instances" for base scene children overrides, "conn_count" and "conns" for signal connections, and "version" for the format style of the PackedScene. + Available keys include "rnames" and "variants" for resources, "node_count", "nodes", "node_paths" for nodes, "editable_instances" for paths to overridden nodes, "conn_count" and "conns" for signal connections, and "version" for the format style of the PackedScene. </member> </members> <constants> diff --git a/doc/classes/PackedStringArray.xml b/doc/classes/PackedStringArray.xml index bc4fce3417..5a55bed82d 100644 --- a/doc/classes/PackedStringArray.xml +++ b/doc/classes/PackedStringArray.xml @@ -135,7 +135,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedVector2Array.xml b/doc/classes/PackedVector2Array.xml index 00af08a7b9..b6766d7a99 100644 --- a/doc/classes/PackedVector2Array.xml +++ b/doc/classes/PackedVector2Array.xml @@ -137,7 +137,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PackedVector3Array.xml b/doc/classes/PackedVector3Array.xml index 64727a313d..e610dea0a4 100644 --- a/doc/classes/PackedVector3Array.xml +++ b/doc/classes/PackedVector3Array.xml @@ -136,7 +136,7 @@ <return type="int" /> <param index="0" name="new_size" type="int" /> <description> - Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. + Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling [method resize] once and assigning the new values is faster than adding new elements one by one. </description> </method> <method name="reverse"> diff --git a/doc/classes/PacketPeerUDP.xml b/doc/classes/PacketPeerUDP.xml index bd774ac34c..12d3178797 100644 --- a/doc/classes/PacketPeerUDP.xml +++ b/doc/classes/PacketPeerUDP.xml @@ -19,7 +19,7 @@ Binds this [PacketPeerUDP] to the specified [param port] and [param bind_address] with a buffer size [param recv_buf_size], allowing it to receive incoming packets. If [param bind_address] is set to [code]"*"[/code] (default), the peer will be bound on all available addresses (both IPv4 and IPv6). If [param bind_address] is set to [code]"0.0.0.0"[/code] (for IPv4) or [code]"::"[/code] (for IPv6), the peer will be bound to all available addresses matching that IP type. - If [param bind_address] is set to any valid address (e.g. [code]"192.168.1.101"[/code], [code]"::1"[/code], etc), the peer will only be bound to the interface with that addresses (or fail if no interface with the given address exists). + If [param bind_address] is set to any valid address (e.g. [code]"192.168.1.101"[/code], [code]"::1"[/code], etc.), the peer will only be bound to the interface with that address (or fail if no interface with the given address exists). </description> </method> <method name="close"> @@ -121,7 +121,7 @@ return [/gdscript] [csharp] - var socket = new PacketPeerUDP(); + var socket = new PacketPeerUdp(); // Server socket.SetDestAddress("127.0.0.1", 789); socket.PutPacket("Time to stop".ToAsciiBuffer()); diff --git a/doc/classes/PanoramaSkyMaterial.xml b/doc/classes/PanoramaSkyMaterial.xml index 0d041b9b90..9e579cc7e5 100644 --- a/doc/classes/PanoramaSkyMaterial.xml +++ b/doc/classes/PanoramaSkyMaterial.xml @@ -11,6 +11,9 @@ <tutorials> </tutorials> <members> + <member name="energy_multiplier" type="float" setter="set_energy_multiplier" getter="get_energy_multiplier" default="1.0"> + The sky's overall brightness multiplier. Higher values result in a brighter sky. + </member> <member name="filter" type="bool" setter="set_filtering_enabled" getter="is_filtering_enabled" default="true"> A boolean value to determine if the background texture should be filtered or not. </member> diff --git a/doc/classes/Parallax2D.xml b/doc/classes/Parallax2D.xml new file mode 100644 index 0000000000..472aeb0bd3 --- /dev/null +++ b/doc/classes/Parallax2D.xml @@ -0,0 +1,47 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="Parallax2D" inherits="Node2D" experimental="This node is meant to replace [ParallaxBackground] and [ParallaxLayer]. The implementation may change in the future." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A node used to create a parallax scrolling background. + </brief_description> + <description> + A [Parallax2D] is used to create a parallax effect. It can move at a different speed relative to the camera movement using [member scroll_scale]. This creates an illusion of depth in a 2D game. If manual scrolling is desired, the [Camera2D] position can be ignored with [member ignore_camera_scroll]. + [b]Note:[/b] Any changes to this node's position made after it enters the scene tree will be overridden if [member ignore_camera_scroll] is [code]false[/code] or [member screen_offset] is modified. + </description> + <tutorials> + </tutorials> + <members> + <member name="autoscroll" type="Vector2" setter="set_autoscroll" getter="get_autoscroll" default="Vector2(0, 0)"> + Velocity at which the offset scrolls automatically, in pixels per second. + </member> + <member name="follow_viewport" type="bool" setter="set_follow_viewport" getter="get_follow_viewport" default="true"> + If [code]true[/code], this [Parallax2D] is offset by the current camera's position. If the [Parallax2D] is in a [CanvasLayer] separate from the current camera, it may be desired to match the value with [member CanvasLayer.follow_viewport_enabled]. + </member> + <member name="ignore_camera_scroll" type="bool" setter="set_ignore_camera_scroll" getter="is_ignore_camera_scroll" default="false"> + If [code]true[/code], [Parallax2D]'s position is not affected by the position of the camera. + </member> + <member name="limit_begin" type="Vector2" setter="set_limit_begin" getter="get_limit_begin" default="Vector2(-1e+07, -1e+07)"> + Top-left limits for scrolling to begin. If the camera is outside of this limit, the [Parallax2D] stops scrolling. Must be lower than [member limit_end] minus the viewport size to work. + </member> + <member name="limit_end" type="Vector2" setter="set_limit_end" getter="get_limit_end" default="Vector2(1e+07, 1e+07)"> + Bottom-right limits for scrolling to end. If the camera is outside of this limit, the [Parallax2D] will stop scrolling. Must be higher than [member limit_begin] and the viewport size combined to work. + </member> + <member name="physics_interpolation_mode" type="int" setter="set_physics_interpolation_mode" getter="get_physics_interpolation_mode" overrides="Node" enum="Node.PhysicsInterpolationMode" default="2" /> + <member name="repeat_size" type="Vector2" setter="set_repeat_size" getter="get_repeat_size" default="Vector2(0, 0)"> + Repeats the [Texture2D] of each of this node's children and offsets them by this value. When scrolling, the node's position loops, giving the illusion of an infinite scrolling background if the values are larger than the screen size. If an axis is set to [code]0[/code], the [Texture2D] will not be repeated. + </member> + <member name="repeat_times" type="int" setter="set_repeat_times" getter="get_repeat_times" default="1"> + Overrides the amount of times the texture repeats. Each texture copy spreads evenly from the original by [member repeat_size]. Useful for when zooming out with a camera. + </member> + <member name="screen_offset" type="Vector2" setter="set_screen_offset" getter="get_screen_offset" default="Vector2(0, 0)"> + Offset used to scroll this [Parallax2D]. This value is updated automatically unless [member ignore_camera_scroll] is [code]true[/code]. + </member> + <member name="scroll_offset" type="Vector2" setter="set_scroll_offset" getter="get_scroll_offset" default="Vector2(0, 0)"> + The [Parallax2D]'s offset. Similar to [member screen_offset] and [member Node2D.position], but will not be overridden. + [b]Note:[/b] Values will loop if [member repeat_size] is set higher than [code]0[/code]. + </member> + <member name="scroll_scale" type="Vector2" setter="set_scroll_scale" getter="get_scroll_scale" default="Vector2(1, 1)"> + Multiplier to the final [Parallax2D]'s offset. Can be used to simulate distance from the camera. + For example, a value of [code]1[/code] scrolls at the same speed as the camera. A value greater than [code]1[/code] scrolls faster, making objects appear closer. Less than [code]1[/code] scrolls slower, making objects appear further, and a value of [code]0[/code] stops the objects completely. + </member> + </members> +</class> diff --git a/doc/classes/ParallaxLayer.xml b/doc/classes/ParallaxLayer.xml index 86ac2165d8..12482d6f66 100644 --- a/doc/classes/ParallaxLayer.xml +++ b/doc/classes/ParallaxLayer.xml @@ -12,9 +12,10 @@ </tutorials> <members> <member name="motion_mirroring" type="Vector2" setter="set_mirroring" getter="get_mirroring" default="Vector2(0, 0)"> - The ParallaxLayer's [Texture2D] repeating. Useful for creating an infinite scrolling background. If an axis is set to [code]0[/code], the [Texture2D] will not be repeated. - If the length of the viewport axis is bigger than twice the repeated axis size, it will not repeat infinitely, as the parallax layer only draws 2 instances of the texture at any given time. - [b]Note:[/b] Despite its name, the texture will not be mirrored, it will simply be repeated. + The interval, in pixels, at which the [ParallaxLayer] is drawn repeatedly. Useful for creating an infinitely scrolling background. If an axis is set to [code]0[/code], the [ParallaxLayer] will be drawn only once along that direction. + [b]Note:[/b] If you want the repetition to pixel-perfect match a [Texture2D] displayed by a child node, you should account for any scale applied to the texture when defining this interval. For example, if you use a child [Sprite2D] scaled to [code]0.5[/code] to display a 600x600 texture, and want this sprite to be repeated continuously horizontally, you should set the mirroring to [code]Vector2(300, 0)[/code]. + [b]Note:[/b] If the length of the viewport axis is bigger than twice the repeated axis size, it will not repeat infinitely, as the parallax layer only draws 2 instances of the layer at any given time. The visibility window is calculated from the parent [ParallaxBackground]'s position, not the layer's own position. So, if you use mirroring, [b]do not[/b] change the [ParallaxLayer] position relative to its parent. Instead, if you need to adjust the background's position, set the [member CanvasLayer.offset] property in the parent [ParallaxBackground]. + [b]Note:[/b] Despite the name, the layer will not be mirrored, it will only be repeated. </member> <member name="motion_offset" type="Vector2" setter="set_motion_offset" getter="get_motion_offset" default="Vector2(0, 0)"> The ParallaxLayer's offset relative to the parent ParallaxBackground's [member ParallaxBackground.scroll_offset]. @@ -22,5 +23,6 @@ <member name="motion_scale" type="Vector2" setter="set_motion_scale" getter="get_motion_scale" default="Vector2(1, 1)"> Multiplies the ParallaxLayer's motion. If an axis is set to [code]0[/code], it will not scroll. </member> + <member name="physics_interpolation_mode" type="int" setter="set_physics_interpolation_mode" getter="get_physics_interpolation_mode" overrides="Node" enum="Node.PhysicsInterpolationMode" default="2" /> </members> </class> diff --git a/doc/classes/ParticleProcessMaterial.xml b/doc/classes/ParticleProcessMaterial.xml index aa20260849..8d0ae317b9 100644 --- a/doc/classes/ParticleProcessMaterial.xml +++ b/doc/classes/ParticleProcessMaterial.xml @@ -9,6 +9,14 @@ <tutorials> </tutorials> <methods> + <method name="get_param" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="param" type="int" enum="ParticleProcessMaterial.Parameter" /> + <description> + Returns the minimum and maximum values of the given [param param] as a vector. + The [code]x[/code] component of the returned vector corresponds to minimum and the [code]y[/code] component corresponds to maximum. + </description> + </method> <method name="get_param_max" qualifiers="const"> <return type="float" /> <param index="0" name="param" type="int" enum="ParticleProcessMaterial.Parameter" /> @@ -37,6 +45,15 @@ Returns [code]true[/code] if the specified particle flag is enabled. See [enum ParticleFlags] for options. </description> </method> + <method name="set_param"> + <return type="void" /> + <param index="0" name="param" type="int" enum="ParticleProcessMaterial.Parameter" /> + <param index="1" name="value" type="Vector2" /> + <description> + Sets the minimum and maximum values of the given [param param]. + The [code]x[/code] component of the argument vector corresponds to minimum and the [code]y[/code] component corresponds to maximum. + </description> + </method> <method name="set_param_max"> <return type="void" /> <param index="0" name="param" type="int" enum="ParticleProcessMaterial.Parameter" /> @@ -130,7 +147,7 @@ <member name="collision_use_scale" type="bool" setter="set_collision_use_scale" getter="is_collision_using_scale" default="false"> If [code]true[/code], [member GPUParticles3D.collision_base_size] is multiplied by the particle's effective scale (see [member scale_min], [member scale_max], [member scale_curve], and [member scale_over_velocity_curve]). </member> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour"> Each particle's initial color. If the [GPUParticles2D]'s [code]texture[/code] is defined, it will be multiplied by this color. [b]Note:[/b] [member color] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color] will have no visible effect. </member> @@ -293,7 +310,7 @@ [b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead. </member> <member name="scale_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture"> - Each particle's scale will vary along this [CurveTexture]. If a [CurveXYZTexture] is supplied instead, the scale will be separated per-axis. + Each particle's scale will vary along this [CurveTexture] over its lifetime. If a [CurveXYZTexture] is supplied instead, the scale will be separated per-axis. </member> <member name="scale_max" type="float" setter="set_param_max" getter="get_param_max" default="1.0"> Maximum initial scale applied to each particle. diff --git a/doc/classes/PhysicalBone2D.xml b/doc/classes/PhysicalBone2D.xml index b22b246978..db8c61ed54 100644 --- a/doc/classes/PhysicalBone2D.xml +++ b/doc/classes/PhysicalBone2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="PhysicalBone2D" inherits="RigidBody2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="PhysicalBone2D" inherits="RigidBody2D" keywords="ragdoll" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A [RigidBody2D]-derived node used to make [Bone2D]s in a [Skeleton2D] react to physics. </brief_description> diff --git a/doc/classes/PhysicalBone3D.xml b/doc/classes/PhysicalBone3D.xml index b69fb7050e..c3b202e0a5 100644 --- a/doc/classes/PhysicalBone3D.xml +++ b/doc/classes/PhysicalBone3D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="PhysicalBone3D" inherits="PhysicsBody3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="PhysicalBone3D" inherits="PhysicsBody3D" keywords="ragdoll" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A physics body used to make bones in a [Skeleton3D] react to physics. </brief_description> @@ -61,6 +61,7 @@ </member> <member name="bounce" type="float" setter="set_bounce" getter="get_bounce" default="0.0"> The body's bounciness. Values range from [code]0[/code] (no bounce) to [code]1[/code] (full bounciness). + [b]Note:[/b] Even with [member bounce] set to [code]1.0[/code], some energy will be lost over time due to linear and angular damping. To have a [PhysicalBone3D] that preserves all its energy over time, set [member bounce] to [code]1.0[/code], [member linear_damp_mode] to [constant DAMP_MODE_REPLACE], [member linear_damp] to [code]0.0[/code], [member angular_damp_mode] to [constant DAMP_MODE_REPLACE], and [member angular_damp] to [code]0.0[/code]. </member> <member name="can_sleep" type="bool" setter="set_can_sleep" getter="is_able_to_sleep" default="true"> If [code]true[/code], the body is deactivated when there is no movement, so it will not take part in the simulation until it is awakened by an external force. diff --git a/doc/classes/PhysicalBoneSimulator3D.xml b/doc/classes/PhysicalBoneSimulator3D.xml new file mode 100644 index 0000000000..149993e1e2 --- /dev/null +++ b/doc/classes/PhysicalBoneSimulator3D.xml @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="PhysicalBoneSimulator3D" inherits="SkeletonModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Node that can be the parent of [PhysicalBone3D] and can apply the simulation results to [Skeleton3D]. + </brief_description> + <description> + Node that can be the parent of [PhysicalBone3D] and can apply the simulation results to [Skeleton3D]. + </description> + <tutorials> + </tutorials> + <methods> + <method name="is_simulating_physics" qualifiers="const"> + <return type="bool" /> + <description> + Returns a boolean that indicates whether the [PhysicalBoneSimulator3D] is running and simulating. + </description> + </method> + <method name="physical_bones_add_collision_exception"> + <return type="void" /> + <param index="0" name="exception" type="RID" /> + <description> + Adds a collision exception to the physical bone. + Works just like the [RigidBody3D] node. + </description> + </method> + <method name="physical_bones_remove_collision_exception"> + <return type="void" /> + <param index="0" name="exception" type="RID" /> + <description> + Removes a collision exception to the physical bone. + Works just like the [RigidBody3D] node. + </description> + </method> + <method name="physical_bones_start_simulation"> + <return type="void" /> + <param index="0" name="bones" type="StringName[]" default="[]" /> + <description> + Tells the [PhysicalBone3D] nodes in the Skeleton to start simulating and reacting to the physics world. + Optionally, a list of bone names can be passed-in, allowing only the passed-in bones to be simulated. + </description> + </method> + <method name="physical_bones_stop_simulation"> + <return type="void" /> + <description> + Tells the [PhysicalBone3D] nodes in the Skeleton to stop simulating. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/PhysicsBody2D.xml b/doc/classes/PhysicsBody2D.xml index adfdfdc445..fa3bb941bf 100644 --- a/doc/classes/PhysicsBody2D.xml +++ b/doc/classes/PhysicsBody2D.xml @@ -23,6 +23,12 @@ Returns an array of nodes that were added as collision exceptions for this body. </description> </method> + <method name="get_gravity" qualifiers="const"> + <return type="Vector2" /> + <description> + Returns the gravity vector computed from all sources that can affect the body, including all gravity overrides from [Area2D] nodes and the global world gravity. + </description> + </method> <method name="move_and_collide"> <return type="KinematicCollision2D" /> <param index="0" name="motion" type="Vector2" /> @@ -44,7 +50,7 @@ Removes a body from the list of bodies that this body can't collide with. </description> </method> - <method name="test_move"> + <method name="test_move" keywords="check, collision, sweep"> <return type="bool" /> <param index="0" name="from" type="Transform2D" /> <param index="1" name="motion" type="Vector2" /> diff --git a/doc/classes/PhysicsBody3D.xml b/doc/classes/PhysicsBody3D.xml index ff994fe6c5..5019da35c8 100644 --- a/doc/classes/PhysicsBody3D.xml +++ b/doc/classes/PhysicsBody3D.xml @@ -31,6 +31,12 @@ Returns an array of nodes that were added as collision exceptions for this body. </description> </method> + <method name="get_gravity" qualifiers="const"> + <return type="Vector3" /> + <description> + Returns the gravity vector computed from all sources that can affect the body, including all gravity overrides from [Area3D] nodes and the global world gravity. + </description> + </method> <method name="move_and_collide"> <return type="KinematicCollision3D" /> <param index="0" name="motion" type="Vector3" /> @@ -62,7 +68,7 @@ Locks or unlocks the specified linear or rotational [param axis] depending on the value of [param lock]. </description> </method> - <method name="test_move"> + <method name="test_move" keywords="check, collision, sweep"> <return type="bool" /> <param index="0" name="from" type="Transform3D" /> <param index="1" name="motion" type="Vector3" /> diff --git a/doc/classes/PhysicsMaterial.xml b/doc/classes/PhysicsMaterial.xml index 30c2400775..1601a1040e 100644 --- a/doc/classes/PhysicsMaterial.xml +++ b/doc/classes/PhysicsMaterial.xml @@ -14,6 +14,7 @@ </member> <member name="bounce" type="float" setter="set_bounce" getter="get_bounce" default="0.0"> The body's bounciness. Values range from [code]0[/code] (no bounce) to [code]1[/code] (full bounciness). + [b]Note:[/b] Even with [member bounce] set to [code]1.0[/code], some energy will be lost over time due to linear and angular damping. To have a [PhysicsBody3D] that preserves all its energy over time, set [member bounce] to [code]1.0[/code], the body's linear damp mode to [b]Replace[/b] (if applicable), its linear damp to [code]0.0[/code], its angular damp mode to [b]Replace[/b] (if applicable), and its angular damp to [code]0.0[/code]. </member> <member name="friction" type="float" setter="set_friction" getter="get_friction" default="1.0"> The body's friction. Values range from [code]0[/code] (frictionless) to [code]1[/code] (maximum friction). diff --git a/doc/classes/PhysicsServer3D.xml b/doc/classes/PhysicsServer3D.xml index 32810b0daf..e40d73862b 100644 --- a/doc/classes/PhysicsServer3D.xml +++ b/doc/classes/PhysicsServer3D.xml @@ -740,7 +740,7 @@ <param index="1" name="axis" type="int" enum="Vector3.Axis" /> <param index="2" name="flag" type="int" enum="PhysicsServer3D.G6DOFJointAxisFlag" /> <description> - Gets a generic_6_DOF_joint flag (see [enum G6DOFJointAxisFlag] constants). + Returns the value of a generic 6DOF joint flag. See [enum G6DOFJointAxisFlag] for the list of available flags. </description> </method> <method name="generic_6dof_joint_get_param" qualifiers="const"> @@ -749,7 +749,7 @@ <param index="1" name="axis" type="int" enum="Vector3.Axis" /> <param index="2" name="param" type="int" enum="PhysicsServer3D.G6DOFJointAxisParam" /> <description> - Gets a generic_6_DOF_joint parameter (see [enum G6DOFJointAxisParam] constants). + Returns the value of a generic 6DOF joint parameter. See [enum G6DOFJointAxisParam] for the list of available parameters. </description> </method> <method name="generic_6dof_joint_set_flag"> @@ -759,7 +759,7 @@ <param index="2" name="flag" type="int" enum="PhysicsServer3D.G6DOFJointAxisFlag" /> <param index="3" name="enable" type="bool" /> <description> - Sets a generic_6_DOF_joint flag (see [enum G6DOFJointAxisFlag] constants). + Sets the value of a given generic 6DOF joint flag. See [enum G6DOFJointAxisFlag] for the list of available flags. </description> </method> <method name="generic_6dof_joint_set_param"> @@ -769,7 +769,7 @@ <param index="2" name="param" type="int" enum="PhysicsServer3D.G6DOFJointAxisParam" /> <param index="3" name="value" type="float" /> <description> - Sets a generic_6_DOF_joint parameter (see [enum G6DOFJointAxisParam] constants). + Sets the value of a given generic 6DOF joint parameter. See [enum G6DOFJointAxisParam] for the list of available parameters. </description> </method> <method name="get_process_info"> @@ -876,6 +876,7 @@ <param index="3" name="body_B" type="RID" /> <param index="4" name="local_ref_B" type="Transform3D" /> <description> + Make the joint a generic six degrees of freedom (6DOF) joint. Use [method generic_6dof_joint_set_flag] and [method generic_6dof_joint_set_param] to set the joint's flags and parameters respectively. </description> </method> <method name="joint_make_hinge"> @@ -1014,10 +1015,262 @@ Gets a slider_joint parameter (see [enum SliderJointParam] constants). </description> </method> + <method name="soft_body_add_collision_exception"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="body_b" type="RID" /> + <description> + Adds the given body to the list of bodies exempt from collisions. + </description> + </method> + <method name="soft_body_create"> + <return type="RID" /> + <description> + Creates a new soft body and returns its internal [RID]. + </description> + </method> <method name="soft_body_get_bounds" qualifiers="const"> <return type="AABB" /> <param index="0" name="body" type="RID" /> <description> + Returns the bounds of the given soft body in global coordinates. + </description> + </method> + <method name="soft_body_get_collision_layer" qualifiers="const"> + <return type="int" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the physics layer or layers that the given soft body belongs to. + </description> + </method> + <method name="soft_body_get_collision_mask" qualifiers="const"> + <return type="int" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the physics layer or layers that the given soft body can collide with. + </description> + </method> + <method name="soft_body_get_damping_coefficient" qualifiers="const"> + <return type="float" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the damping coefficient of the given soft body. + </description> + </method> + <method name="soft_body_get_drag_coefficient" qualifiers="const"> + <return type="float" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the drag coefficient of the given soft body. + </description> + </method> + <method name="soft_body_get_linear_stiffness" qualifiers="const"> + <return type="float" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the linear stiffness of the given soft body. + </description> + </method> + <method name="soft_body_get_point_global_position" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="point_index" type="int" /> + <description> + Returns the current position of the given soft body point in global coordinates. + </description> + </method> + <method name="soft_body_get_pressure_coefficient" qualifiers="const"> + <return type="float" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the pressure coefficient of the given soft body. + </description> + </method> + <method name="soft_body_get_simulation_precision" qualifiers="const"> + <return type="int" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the simulation precision of the given soft body. + </description> + </method> + <method name="soft_body_get_space" qualifiers="const"> + <return type="RID" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the [RID] of the space assigned to the given soft body. + </description> + </method> + <method name="soft_body_get_state" qualifiers="const"> + <return type="Variant" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="state" type="int" enum="PhysicsServer3D.BodyState" /> + <description> + Returns the given soft body state (see [enum BodyState] constants). + [b]Note:[/b] Godot's default physics implementation does not support [constant BODY_STATE_LINEAR_VELOCITY], [constant BODY_STATE_ANGULAR_VELOCITY], [constant BODY_STATE_SLEEPING], or [constant BODY_STATE_CAN_SLEEP]. + </description> + </method> + <method name="soft_body_get_total_mass" qualifiers="const"> + <return type="float" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the total mass assigned to the given soft body. + </description> + </method> + <method name="soft_body_is_point_pinned" qualifiers="const"> + <return type="bool" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="point_index" type="int" /> + <description> + Returns whether the given soft body point is pinned. + </description> + </method> + <method name="soft_body_move_point"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="point_index" type="int" /> + <param index="2" name="global_position" type="Vector3" /> + <description> + Moves the given soft body point to a position in global coordinates. + </description> + </method> + <method name="soft_body_pin_point"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="point_index" type="int" /> + <param index="2" name="pin" type="bool" /> + <description> + Pins or unpins the given soft body point based on the value of [param pin]. + [b]Note:[/b] Pinning a point effectively makes it kinematic, preventing it from being affected by forces, but you can still move it using [method soft_body_move_point]. + </description> + </method> + <method name="soft_body_remove_all_pinned_points"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <description> + Unpins all points of the given soft body. + </description> + </method> + <method name="soft_body_remove_collision_exception"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="body_b" type="RID" /> + <description> + Removes the given body from the list of bodies exempt from collisions. + </description> + </method> + <method name="soft_body_set_collision_layer"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="layer" type="int" /> + <description> + Sets the physics layer or layers the given soft body belongs to. + </description> + </method> + <method name="soft_body_set_collision_mask"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="mask" type="int" /> + <description> + Sets the physics layer or layers the given soft body can collide with. + </description> + </method> + <method name="soft_body_set_damping_coefficient"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="damping_coefficient" type="float" /> + <description> + Sets the damping coefficient of the given soft body. Higher values will slow down the body more noticeably when forces are applied. + </description> + </method> + <method name="soft_body_set_drag_coefficient"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="drag_coefficient" type="float" /> + <description> + Sets the drag coefficient of the given soft body. Higher values increase this body's air resistance. + [b]Note:[/b] This value is currently unused by Godot's default physics implementation. + </description> + </method> + <method name="soft_body_set_linear_stiffness"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="stiffness" type="float" /> + <description> + Sets the linear stiffness of the given soft body. Higher values will result in a stiffer body, while lower values will increase the body's ability to bend. The value can be between [code]0.0[/code] and [code]1.0[/code] (inclusive). + </description> + </method> + <method name="soft_body_set_mesh"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="mesh" type="RID" /> + <description> + Sets the mesh of the given soft body. + </description> + </method> + <method name="soft_body_set_pressure_coefficient"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="pressure_coefficient" type="float" /> + <description> + Sets the pressure coefficient of the given soft body. Simulates pressure build-up from inside this body. Higher values increase the strength of this effect. + </description> + </method> + <method name="soft_body_set_ray_pickable"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="enable" type="bool" /> + <description> + Sets whether the given soft body will be pickable when using object picking. + </description> + </method> + <method name="soft_body_set_simulation_precision"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="simulation_precision" type="int" /> + <description> + Sets the simulation precision of the given soft body. Increasing this value will improve the resulting simulation, but can affect performance. Use with care. + </description> + </method> + <method name="soft_body_set_space"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="space" type="RID" /> + <description> + Assigns a space to the given soft body (see [method space_create]). + </description> + </method> + <method name="soft_body_set_state"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="state" type="int" enum="PhysicsServer3D.BodyState" /> + <param index="2" name="variant" type="Variant" /> + <description> + Sets the given body state for the given body (see [enum BodyState] constants). + [b]Note:[/b] Godot's default physics implementation does not support [constant BODY_STATE_LINEAR_VELOCITY], [constant BODY_STATE_ANGULAR_VELOCITY], [constant BODY_STATE_SLEEPING], or [constant BODY_STATE_CAN_SLEEP]. + </description> + </method> + <method name="soft_body_set_total_mass"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="total_mass" type="float" /> + <description> + Sets the total mass for the given soft body. + </description> + </method> + <method name="soft_body_set_transform"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="transform" type="Transform3D" /> + <description> + Sets the global transform of the given soft body. + </description> + </method> + <method name="soft_body_update_rendering_server"> + <return type="void" /> + <param index="0" name="body" type="RID" /> + <param index="1" name="rendering_server_handler" type="PhysicsServer3DRenderingServerHandler" /> + <description> + Requests that the physics server updates the rendering server with the latest positions of the given soft body's points through the [param rendering_server_handler] interface. </description> </method> <method name="space_create"> @@ -1245,6 +1498,12 @@ <constant name="G6DOF_JOINT_LINEAR_MOTOR_FORCE_LIMIT" value="6" enum="G6DOFJointAxisParam"> The maximum force that the linear motor can apply while trying to reach the target velocity. </constant> + <constant name="G6DOF_JOINT_LINEAR_SPRING_STIFFNESS" value="7" enum="G6DOFJointAxisParam"> + </constant> + <constant name="G6DOF_JOINT_LINEAR_SPRING_DAMPING" value="8" enum="G6DOFJointAxisParam"> + </constant> + <constant name="G6DOF_JOINT_LINEAR_SPRING_EQUILIBRIUM_POINT" value="9" enum="G6DOFJointAxisParam"> + </constant> <constant name="G6DOF_JOINT_ANGULAR_LOWER_LIMIT" value="10" enum="G6DOFJointAxisParam"> The minimum rotation in negative direction to break loose and rotate around the axes. </constant> @@ -1272,18 +1531,34 @@ <constant name="G6DOF_JOINT_ANGULAR_MOTOR_FORCE_LIMIT" value="18" enum="G6DOFJointAxisParam"> Maximum acceleration for the motor at the axes. </constant> + <constant name="G6DOF_JOINT_ANGULAR_SPRING_STIFFNESS" value="19" enum="G6DOFJointAxisParam"> + </constant> + <constant name="G6DOF_JOINT_ANGULAR_SPRING_DAMPING" value="20" enum="G6DOFJointAxisParam"> + </constant> + <constant name="G6DOF_JOINT_ANGULAR_SPRING_EQUILIBRIUM_POINT" value="21" enum="G6DOFJointAxisParam"> + </constant> + <constant name="G6DOF_JOINT_MAX" value="22" enum="G6DOFJointAxisParam"> + Represents the size of the [enum G6DOFJointAxisParam] enum. + </constant> <constant name="G6DOF_JOINT_FLAG_ENABLE_LINEAR_LIMIT" value="0" enum="G6DOFJointAxisFlag"> If set, linear motion is possible within the given limits. </constant> <constant name="G6DOF_JOINT_FLAG_ENABLE_ANGULAR_LIMIT" value="1" enum="G6DOFJointAxisFlag"> If set, rotational motion is possible. </constant> + <constant name="G6DOF_JOINT_FLAG_ENABLE_ANGULAR_SPRING" value="2" enum="G6DOFJointAxisFlag"> + </constant> + <constant name="G6DOF_JOINT_FLAG_ENABLE_LINEAR_SPRING" value="3" enum="G6DOFJointAxisFlag"> + </constant> <constant name="G6DOF_JOINT_FLAG_ENABLE_MOTOR" value="4" enum="G6DOFJointAxisFlag"> If set, there is a rotational motor across these axes. </constant> <constant name="G6DOF_JOINT_FLAG_ENABLE_LINEAR_MOTOR" value="5" enum="G6DOFJointAxisFlag"> If set, there is a linear motor on this axis that targets a specific velocity. </constant> + <constant name="G6DOF_JOINT_FLAG_MAX" value="6" enum="G6DOFJointAxisFlag"> + Represents the size of the [enum G6DOFJointAxisFlag] enum. + </constant> <constant name="SHAPE_WORLD_BOUNDARY" value="0" enum="ShapeType"> The [Shape3D] is a [WorldBoundaryShape3D]. </constant> diff --git a/doc/classes/PointLight2D.xml b/doc/classes/PointLight2D.xml index 556ad50cb1..9af3667126 100644 --- a/doc/classes/PointLight2D.xml +++ b/doc/classes/PointLight2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="PointLight2D" inherits="Light2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="PointLight2D" inherits="Light2D" keywords="omni, spot" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Positional 2D light source. </brief_description> diff --git a/doc/classes/Polygon2D.xml b/doc/classes/Polygon2D.xml index 25adc57990..029a69a399 100644 --- a/doc/classes/Polygon2D.xml +++ b/doc/classes/Polygon2D.xml @@ -74,7 +74,7 @@ <member name="bones" type="Array" setter="_set_bones" getter="_get_bones" default="[]"> Internal list of [Bone2D] nodes used by the assigned [member skeleton]. Edited using the Polygon2D editor ("UV" button on the top toolbar). </member> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour"> The polygon's fill color. If [member texture] is set, it will be multiplied by this color. It will also be the default color for vertices not set in [member vertex_colors]. </member> <member name="internal_vertex_count" type="int" setter="set_internal_vertex_count" getter="get_internal_vertex_count" default="0"> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 3f4ec1b677..7831ebd1b9 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -133,8 +133,25 @@ <param index="4" name="accel" type="int" enum="Key" default="0" /> <description> Adds a new multistate item with text [param label]. - Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. Each press or activate of the item will increase the state by one. The default value is defined by [param default_state]. + Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. The default value is defined by [param default_state]. An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. + [b]Note:[/b] Multistate items don't update their state automatically and must be done manually. See [method toggle_item_multistate], [method set_item_multistate] and [method get_item_multistate] for more info on how to control it. + Example usage: + [codeblock] + func _ready(): + add_multistate_item("Item", 3, 0) + + index_pressed.connect(func(index: int): + toggle_item_multistate(index) + match get_item_multistate(index): + 0: + print("First state") + 1: + print("Second state") + 2: + print("Third state") + ) + [/codeblock] </description> </method> <method name="add_radio_check_item"> @@ -180,7 +197,7 @@ If [param allow_echo] is [code]true[/code], the shortcut can be activated with echo events. </description> </method> - <method name="add_submenu_item"> + <method name="add_submenu_item" deprecated="Prefer using [method add_submenu_node_item] instead."> <return type="void" /> <param index="0" name="label" type="String" /> <param index="1" name="submenu" type="String" /> @@ -190,6 +207,17 @@ An [param id] can optionally be provided. If no [param id] is provided, one will be created from the index. </description> </method> + <method name="add_submenu_node_item"> + <return type="void" /> + <param index="0" name="label" type="String" /> + <param index="1" name="submenu" type="PopupMenu" /> + <param index="2" name="id" type="int" default="-1" /> + <description> + Adds an item that will act as a submenu of the parent [PopupMenu] node when clicked. This submenu will be shown when the item is clicked, hovered for long enough, or activated using the [code]ui_select[/code] or [code]ui_right[/code] input actions. + [param submenu] must be either child of this [PopupMenu] or has no parent node (in which case it will be automatically added as a child). If the [param submenu] popup has another parent, this method will fail. + An [param id] can optionally be provided. If no [param id] is provided, one will be created from the index. + </description> + </method> <method name="clear"> <return type="void" /> <param index="0" name="free_submenus" type="bool" default="false" /> @@ -266,6 +294,20 @@ Returns the metadata of the specified item, which might be of any type. You can set it with [method set_item_metadata], which provides a simple way of assigning context data to items. </description> </method> + <method name="get_item_multistate" qualifiers="const"> + <return type="int" /> + <param index="0" name="index" type="int" /> + <description> + Returns the state of the item at the given [param index]. + </description> + </method> + <method name="get_item_multistate_max" qualifiers="const"> + <return type="int" /> + <param index="0" name="index" type="int" /> + <description> + Returns the max states of the item at the given [param index]. + </description> + </method> <method name="get_item_shortcut" qualifiers="const"> <return type="Shortcut" /> <param index="0" name="index" type="int" /> @@ -273,13 +315,20 @@ Returns the [Shortcut] associated with the item at the given [param index]. </description> </method> - <method name="get_item_submenu" qualifiers="const"> + <method name="get_item_submenu" qualifiers="const" deprecated="Prefer using [method get_item_submenu_node] instead."> <return type="String" /> <param index="0" name="index" type="int" /> <description> Returns the submenu name of the item at the given [param index]. See [method add_submenu_item] for more info on how to add a submenu. </description> </method> + <method name="get_item_submenu_node" qualifiers="const"> + <return type="PopupMenu" /> + <param index="0" name="index" type="int" /> + <description> + Returns the submenu of the item at the given [param index], or [code]null[/code] if no submenu was added. See [method add_submenu_node_item] for more info on how to add a submenu. + </description> + </method> <method name="get_item_text" qualifiers="const"> <return type="String" /> <param index="0" name="index" type="int" /> @@ -346,6 +395,12 @@ Returns [code]true[/code] if the specified item's shortcut is disabled. </description> </method> + <method name="is_system_menu" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the menu is bound to the special system menu. + </description> + </method> <method name="remove_item"> <return type="void" /> <param index="0" name="index" type="int" /> @@ -483,6 +538,14 @@ Sets the state of a multistate item. See [method add_multistate_item] for details. </description> </method> + <method name="set_item_multistate_max"> + <return type="void" /> + <param index="0" name="index" type="int" /> + <param index="1" name="max_states" type="int" /> + <description> + Sets the max states of a multistate item. See [method add_multistate_item] for details. + </description> + </method> <method name="set_item_shortcut"> <return type="void" /> <param index="0" name="index" type="int" /> @@ -500,7 +563,7 @@ Disables the [Shortcut] of the item at the given [param index]. </description> </method> - <method name="set_item_submenu"> + <method name="set_item_submenu" deprecated="Prefer using [method set_item_submenu_node] instead."> <return type="void" /> <param index="0" name="index" type="int" /> <param index="1" name="submenu" type="String" /> @@ -508,6 +571,14 @@ Sets the submenu of the item at the given [param index]. The submenu is the name of a child [PopupMenu] node that would be shown when the item is clicked. </description> </method> + <method name="set_item_submenu_node"> + <return type="void" /> + <param index="0" name="index" type="int" /> + <param index="1" name="submenu" type="PopupMenu" /> + <description> + Sets the submenu of the item at the given [param index]. The submenu is a [PopupMenu] node that would be shown when the item is clicked. It must either be a child of this [PopupMenu] or has no parent (in which case it will be automatically added as a child). If the [param submenu] popup has another parent, this method will fail. + </description> + </method> <method name="set_item_text"> <return type="void" /> <param index="0" name="index" type="int" /> @@ -563,9 +634,15 @@ <member name="item_count" type="int" setter="set_item_count" getter="get_item_count" default="0"> The number of items currently in the list. </member> + <member name="prefer_native_menu" type="bool" setter="set_prefer_native_menu" getter="is_prefer_native_menu" default="false"> + If [code]true[/code], [MenuBar] will use native menu when supported. + </member> <member name="submenu_popup_delay" type="float" setter="set_submenu_popup_delay" getter="get_submenu_popup_delay" default="0.3"> Sets the delay time in seconds for the submenu item to popup on mouse hovering. If the popup menu is added as a child of another (acting as a submenu), it will inherit the delay time of the parent menu item. </member> + <member name="system_menu_id" type="int" setter="set_system_menu" getter="get_system_menu" enum="NativeMenu.SystemMenus" default="0"> + If set to one of the values of [enum NativeMenu.SystemMenus], this [PopupMenu] is bound to the special system menu. Only one [PopupMenu] can be bound to each special menu at a time. + </member> </members> <signals> <signal name="id_focused"> @@ -606,13 +683,13 @@ <theme_item name="font_hover_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)"> [Color] used for the hovered text. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the menu item. </theme_item> <theme_item name="font_separator_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)"> [Color] used for labeled separators' text. See [method add_separator]. </theme_item> - <theme_item name="font_separator_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_separator_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the labeled separator. </theme_item> <theme_item name="h_separation" data_type="constant" type="int" default="4"> diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml index d04d8eea52..58a8da12da 100644 --- a/doc/classes/PrimitiveMesh.xml +++ b/doc/classes/PrimitiveMesh.xml @@ -12,6 +12,7 @@ <method name="_create_mesh_array" qualifiers="virtual const"> <return type="Array" /> <description> + Override this method to customize how this primitive mesh should be generated. Should return an [Array] where each element is another Array of values required for the mesh (see the [enum Mesh.ArrayType] constants). </description> </method> <method name="get_mesh_arrays" qualifiers="const"> @@ -32,6 +33,12 @@ [/codeblocks] </description> </method> + <method name="request_update"> + <return type="void" /> + <description> + Request an update of this primitive mesh based on its properties. + </description> + </method> </methods> <members> <member name="add_uv2" type="bool" setter="set_add_uv2" getter="get_add_uv2" default="false"> diff --git a/doc/classes/ProceduralSkyMaterial.xml b/doc/classes/ProceduralSkyMaterial.xml index 54bffd009f..1503bb2e78 100644 --- a/doc/classes/ProceduralSkyMaterial.xml +++ b/doc/classes/ProceduralSkyMaterial.xml @@ -6,11 +6,14 @@ <description> [ProceduralSkyMaterial] provides a way to create an effective background quickly by defining procedural parameters for the sun, the sky and the ground. The sky and ground are defined by a main color, a color at the horizon, and an easing curve to interpolate between them. Suns are described by a position in the sky, a color, and a max angle from the sun at which the easing curve ends. The max angle therefore defines the size of the sun in the sky. [ProceduralSkyMaterial] supports up to 4 suns, using the color, and energy, direction, and angular distance of the first four [DirectionalLight3D] nodes in the scene. This means that the suns are defined individually by the properties of their corresponding [DirectionalLight3D]s and globally by [member sun_angle_max] and [member sun_curve]. - [ProceduralSkyMaterial] uses a lightweight shader to draw the sky and is therefore suited for real time updates. This makes it a great option for a sky that is simple and computationally cheap, but unrealistic. If you need a more realistic procedural option, use [PhysicalSkyMaterial]. + [ProceduralSkyMaterial] uses a lightweight shader to draw the sky and is therefore suited for real-time updates. This makes it a great option for a sky that is simple and computationally cheap, but unrealistic. If you need a more realistic procedural option, use [PhysicalSkyMaterial]. </description> <tutorials> </tutorials> <members> + <member name="energy_multiplier" type="float" setter="set_energy_multiplier" getter="get_energy_multiplier" default="1.0"> + The sky's overall brightness multiplier. Higher values result in a brighter sky. + </member> <member name="ground_bottom_color" type="Color" setter="set_ground_bottom_color" getter="get_ground_bottom_color" default="Color(0.2, 0.169, 0.133, 1)"> Color of the ground at the bottom. Blends with [member ground_horizon_color]. </member> diff --git a/doc/classes/ProgressBar.xml b/doc/classes/ProgressBar.xml index 1102f0369a..e562d39bb7 100644 --- a/doc/classes/ProgressBar.xml +++ b/doc/classes/ProgressBar.xml @@ -9,9 +9,15 @@ <tutorials> </tutorials> <members> + <member name="editor_preview_indeterminate" type="bool" setter="set_editor_preview_indeterminate" getter="is_editor_preview_indeterminate_enabled"> + If [code]false[/code], the [member indeterminate] animation will be paused in the editor. + </member> <member name="fill_mode" type="int" setter="set_fill_mode" getter="get_fill_mode" default="0"> The fill direction. See [enum FillMode] for possible values. </member> + <member name="indeterminate" type="bool" setter="set_indeterminate" getter="is_indeterminate" default="false"> + When set to [code]true[/code], the progress bar indicates that something is happening with an animation, but does not show the fill percentage or value. + </member> <member name="show_percentage" type="bool" setter="set_show_percentage" getter="is_percentage_shown" default="true"> If [code]true[/code], the fill percentage is displayed on the bar. </member> @@ -34,7 +40,7 @@ <theme_item name="font_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)"> The color of the text. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the [ProgressBar]. </theme_item> <theme_item name="outline_size" data_type="constant" type="int" default="0"> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 3fc9e94427..6a6f53ac60 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -238,6 +238,12 @@ </method> </methods> <members> + <member name="animation/warnings/check_angle_interpolation_type_conflicting" type="bool" setter="" getter="" default="true"> + If [code]true[/code], [AnimationMixer] prints the warning of interpolation being forced to choose the shortest rotation path due to multiple angle interpolation types being mixed in the [AnimationMixer] cache. + </member> + <member name="animation/warnings/check_invalid_track_paths" type="bool" setter="" getter="" default="true"> + If [code]true[/code], [AnimationMixer] prints the warning of no matching object of the track path in the scene. + </member> <member name="application/boot_splash/bg_color" type="Color" setter="" getter="" default="Color(0.14, 0.14, 0.14, 1)"> Background color for the boot splash. </member> @@ -347,12 +353,15 @@ Maximum number of frames per second allowed. A value of [code]0[/code] means "no limit". The actual number of frames per second may still be below this value if the CPU or GPU cannot keep up with the project logic and rendering. Limiting the FPS can be useful to reduce system power consumption, which reduces heat and noise emissions (and improves battery life on mobile devices). If [member display/window/vsync/vsync_mode] is set to [code]Enabled[/code] or [code]Adaptive[/code], it takes precedence and the forced FPS number cannot exceed the monitor's refresh rate. - If [member display/window/vsync/vsync_mode] is [code]Enabled[/code], on monitors with variable refresh rate enabled (G-Sync/FreeSync), using a FPS limit a few frames lower than the monitor's refresh rate will [url=https://blurbusters.com/howto-low-lag-vsync-on/]reduce input lag while avoiding tearing[/url]. + If [member display/window/vsync/vsync_mode] is [code]Enabled[/code], on monitors with variable refresh rate enabled (G-Sync/FreeSync), using an FPS limit a few frames lower than the monitor's refresh rate will [url=https://blurbusters.com/howto-low-lag-vsync-on/]reduce input lag while avoiding tearing[/url]. If [member display/window/vsync/vsync_mode] is [code]Disabled[/code], limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios. See also [member physics/common/physics_ticks_per_second]. This setting can be overridden using the [code]--max-fps <fps>[/code] command line argument (including with a value of [code]0[/code] for unlimited framerate). [b]Note:[/b] This property is only read when the project starts. To change the rendering FPS cap at runtime, set [member Engine.max_fps] instead. </member> + <member name="application/run/print_header" type="bool" setter="" getter="" default="true"> + If [code]true[/code], the engine header is printed in the console on startup. This header describes the current version of the engine, as well as the renderer being used. This behavior can also be disabled on the command line with the [code]--no-header[/code] option. + </member> <member name="audio/buses/channel_disable_threshold_db" type="float" setter="" getter="" default="-60.0"> Audio buses will disable automatically when sound goes below a given dB threshold for a given time. This saves CPU as effects assigned to that bus will no longer do any processing. </member> @@ -406,7 +415,7 @@ [b]Note:[/b] Enabling TTS can cause addition idle CPU usage and interfere with the sleep mode, so consider disabling it if TTS is not used. </member> <member name="audio/video/video_delay_compensation_ms" type="int" setter="" getter="" default="0"> - Setting to hardcode audio delay when playing video. Best to leave this untouched unless you know what you are doing. + Setting to hardcode audio delay when playing video. Best to leave this unchanged unless you know what you are doing. </member> <member name="collada/use_ambient" type="bool" setter="" getter="" default="false"> If [code]true[/code], ambient lights will be imported from COLLADA models as [DirectionalLight3D]. If [code]false[/code], ambient lights will be ignored. @@ -433,16 +442,18 @@ If canvas item redraw debugging is active, this will be the time the flash will last each time they redraw. </member> <member name="debug/file_logging/enable_file_logging" type="bool" setter="" getter="" default="false"> - If [code]true[/code], logs all output to files. + If [code]true[/code], logs all output and error messages to files. See also [member debug/file_logging/log_path], [member debug/file_logging/max_log_files], and [member application/run/flush_stdout_on_print]. </member> <member name="debug/file_logging/enable_file_logging.pc" type="bool" setter="" getter="" default="true"> Desktop override for [member debug/file_logging/enable_file_logging], as log files are not readily accessible on mobile/Web platforms. </member> <member name="debug/file_logging/log_path" type="String" setter="" getter="" default=""user://logs/godot.log""> Path at which to store log files for the project. Using a path under [code]user://[/code] is recommended. + This can be specified manually on the command line using the [code]--log-file <file>[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. If this command line argument is specified, log rotation is automatically disabled (see [member debug/file_logging/max_log_files]). </member> <member name="debug/file_logging/max_log_files" type="int" setter="" getter="" default="5"> - Specifies the maximum number of log files allowed (used for rotation). + Specifies the maximum number of log files allowed (used for rotation). Set to [code]1[/code] to disable log file rotation. + If the [code]--log-file <file>[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url] is used, log rotation is always disabled. </member> <member name="debug/gdscript/warnings/assert_always_false" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an [code]assert[/code] call always evaluates to false. @@ -459,11 +470,12 @@ <member name="debug/gdscript/warnings/confusable_local_usage" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an identifier that will be shadowed below in the block is used. </member> - <member name="debug/gdscript/warnings/constant_used_as_function" type="int" setter="" getter="" default="1"> + <member name="debug/gdscript/warnings/constant_used_as_function" type="int" setter="" getter="" default="1" deprecated="This warning is never produced. Instead, an error is generated if the expression type is known at compile time."> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a constant is used as a function. </member> <member name="debug/gdscript/warnings/deprecated_keyword" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when deprecated keywords are used. + [b]Note:[/b] There are currently no deprecated keywords, so this warning is never produced. </member> <member name="debug/gdscript/warnings/empty_file" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an empty file is parsed. @@ -474,7 +486,7 @@ <member name="debug/gdscript/warnings/exclude_addons" type="bool" setter="" getter="" default="true"> If [code]true[/code], scripts in the [code]res://addons[/code] folder will not generate warnings. </member> - <member name="debug/gdscript/warnings/function_used_as_property" type="int" setter="" getter="" default="1"> + <member name="debug/gdscript/warnings/function_used_as_property" type="int" setter="" getter="" default="1" deprecated="This warning is never produced. When a function is used as a property, a [Callable] is returned."> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a function as if it is a property. </member> <member name="debug/gdscript/warnings/get_node_default_without_onready" type="int" setter="" getter="" default="2"> @@ -508,7 +520,7 @@ <member name="debug/gdscript/warnings/onready_with_export" type="int" setter="" getter="" default="2"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when the [code]@onready[/code] annotation is used together with the [code]@export[/code] annotation, since it may not behave as expected. </member> - <member name="debug/gdscript/warnings/property_used_as_function" type="int" setter="" getter="" default="1"> + <member name="debug/gdscript/warnings/property_used_as_function" type="int" setter="" getter="" default="1" deprecated="This warning is never produced. Instead, an error is generated if the expression type is known at compile time."> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a property as if it is a function. </member> <member name="debug/gdscript/warnings/redundant_await" type="int" setter="" getter="" default="1"> @@ -521,7 +533,7 @@ When enabled, using a property, enum, or function that was renamed since Godot 3 will produce a hint if an error occurs. </member> <member name="debug/gdscript/warnings/return_value_discarded" type="int" setter="" getter="" default="0"> - When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when calling a function without using its return value (by assigning it to a variable or using it as a function argument). Such return values are sometimes used to denote possible errors using the [enum Error] enum. + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when calling a function without using its return value (by assigning it to a variable or using it as a function argument). These return values are sometimes used to indicate possible errors using the [enum Error] enum. </member> <member name="debug/gdscript/warnings/shadowed_global_identifier" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when defining a local or member variable, signal, or enum that would have the same name as a built-in function or global class name, thus shadowing it. @@ -582,7 +594,7 @@ When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a private member variable is never used. </member> <member name="debug/gdscript/warnings/unused_signal" type="int" setter="" getter="" default="1"> - When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a signal is declared but never emitted. + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a signal is declared but never explicitly used in the class. </member> <member name="debug/gdscript/warnings/unused_variable" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a local variable is unused. @@ -615,7 +627,7 @@ If [code]true[/code], enables specific shader warnings (see [code]debug/shader_language/warnings/*[/code] settings). If [code]false[/code], disables all shader warnings. </member> <member name="debug/shader_language/warnings/float_comparison" type="bool" setter="" getter="" default="true"> - When set to [code]true[/code], produces a warning when two floating point numbers are compared directly with the [code]==[/code] operator or the [code]!=[/code] operator. + When set to [code]true[/code], produces a warning when two floating-point numbers are compared directly with the [code]==[/code] operator or the [code]!=[/code] operator. </member> <member name="debug/shader_language/warnings/formatting_error" type="bool" setter="" getter="" default="true"> When set to [code]true[/code], produces a warning upon encountering certain formatting errors. Currently this only checks for empty statements. More formatting errors may be added over time. @@ -740,6 +752,24 @@ <member name="debug/shapes/paths/geometry_width" type="float" setter="" getter="" default="2.0"> Line width of the curve path geometry, visible when "Visible Paths" is enabled in the Debug menu. </member> + <member name="display/display_server/driver" type="String" setter="" getter=""> + Sets the driver to be used by the display server. This property can not be edited directly, instead, set the driver using the platform-specific overrides. + </member> + <member name="display/display_server/driver.android" type="String" setter="" getter=""> + Android override for [member display/display_server/driver]. + </member> + <member name="display/display_server/driver.ios" type="String" setter="" getter=""> + iOS override for [member display/display_server/driver]. + </member> + <member name="display/display_server/driver.linuxbsd" type="String" setter="" getter=""> + LinuxBSD override for [member display/display_server/driver]. + </member> + <member name="display/display_server/driver.macos" type="String" setter="" getter=""> + MacOS override for [member display/display_server/driver]. + </member> + <member name="display/display_server/driver.windows" type="String" setter="" getter=""> + Windows override for [member display/display_server/driver]. + </member> <member name="display/mouse_cursor/custom_image" type="String" setter="" getter="" default=""""> Custom image for the mouse cursor (limited to 256×256). </member> @@ -793,15 +823,18 @@ </member> <member name="display/window/size/initial_position" type="Vector2i" setter="" getter="" default="Vector2i(0, 0)"> Main window initial position (in virtual desktop coordinates), this setting is used only if [member display/window/size/initial_position_type] is set to "Absolute" ([code]0[/code]). + [b]Note:[/b] This setting only affects the exported project, or when the project is run from the command line. In the editor, the value of [member EditorSettings.run/window_placement/rect_custom_position] is used instead. </member> <member name="display/window/size/initial_position_type" type="int" setter="" getter="" default="1"> Main window initial position. [code]0[/code] - "Absolute", [member display/window/size/initial_position] is used to set window position. [code]1[/code] - "Primary Screen Center". [code]2[/code] - "Other Screen Center", [member display/window/size/initial_screen] is used to set the screen. + [b]Note:[/b] This setting only affects the exported project, or when the project is run from the command line. In the editor, the value of [member EditorSettings.run/window_placement/rect] is used instead. </member> <member name="display/window/size/initial_screen" type="int" setter="" getter="" default="0"> Main window initial screen, this setting is used only if [member display/window/size/initial_position_type] is set to "Other Screen Center" ([code]2[/code]). + [b]Note:[/b] This setting only affects the exported project, or when the project is run from the command line. In the editor, the value of [member EditorSettings.run/window_placement/screen] is used instead. </member> <member name="display/window/size/mode" type="int" setter="" getter="" default="0"> Main window mode. See [enum DisplayServer.WindowMode] for possible values and how each mode behaves. @@ -810,7 +843,9 @@ Main window can't be focused. No-focus window will ignore all input, except mouse clicks. </member> <member name="display/window/size/resizable" type="bool" setter="" getter="" default="true"> - Allows the window to be resizable by default. + If [code]true[/code], allows the window to be resizable by default. + [b]Note:[/b] This property is only read when the project starts. To change whether the window is resizable at runtime, set [member Window.unresizable] instead on the root Window, which can be retrieved using [code]get_viewport().get_window()[/code]. [member Window.unresizable] takes the opposite value of this setting. + [b]Note:[/b] Certain window managers can be configured to ignore the non-resizable status of a window. Do not rely on this setting as a guarantee that the window will [i]never[/i] be resizable. [b]Note:[/b] This setting is ignored on iOS. </member> <member name="display/window/size/transparent" type="bool" setter="" getter="" default="false"> @@ -853,7 +888,7 @@ If [code]true[/code] subwindows are embedded in the main window. </member> <member name="display/window/vsync/vsync_mode" type="int" setter="" getter="" default="1"> - Sets the V-Sync mode for the main game window. + Sets the V-Sync mode for the main game window. The editor's own V-Sync mode can be set using [member EditorSettings.interface/editor/vsync_mode]. See [enum DisplayServer.VSyncMode] for possible values and how they affect the behavior of your application. Depending on the platform and used renderer, the engine will fall back to [b]Enabled[/b] if the desired mode is not supported. [b]Note:[/b] V-Sync modes other than [b]Enabled[/b] are only supported in the Forward+ and Mobile rendering methods, not Compatibility. @@ -873,6 +908,9 @@ If [code]true[/code], text resources are converted to a binary format on export. This decreases file sizes and speeds up loading slightly. [b]Note:[/b] If [member editor/export/convert_text_resources_to_binary] is [code]true[/code], [method @GDScript.load] will not be able to return the converted files in an exported project. Some file paths within the exported PCK will also change, such as [code]project.godot[/code] becoming [code]project.binary[/code]. If you rely on run-time loading of files present within the PCK, set [member editor/export/convert_text_resources_to_binary] to [code]false[/code]. </member> + <member name="editor/import/atlas_max_width" type="int" setter="" getter="" default="2048"> + The maximum width to use when importing textures as an atlas. The value will be rounded to the nearest power of two when used. Use this to prevent imported textures from growing too large in the other direction. + </member> <member name="editor/import/reimport_missing_imported_files" type="bool" setter="" getter="" default="true"> </member> <member name="editor/import/use_multiple_threads" type="bool" setter="" getter="" default="true"> @@ -911,18 +949,21 @@ The format of the default signal callback name when a signal connects to the same node that emits it (in the Signal Connection Dialog). The following substitutions are available: [code]{NodeName}[/code], [code]{nodeName}[/code], [code]{node_name}[/code], [code]{SignalName}[/code], [code]{signalName}[/code], and [code]{signal_name}[/code]. </member> <member name="editor/naming/node_name_casing" type="int" setter="" getter="" default="0"> - When creating node names automatically, set the type of casing in this project. This is mostly an editor setting. + When creating node names automatically, set the type of casing to use in this project. This is mostly an editor setting. </member> <member name="editor/naming/node_name_num_separator" type="int" setter="" getter="" default="0"> What to use to separate node name from number. This is mostly an editor setting. </member> <member name="editor/naming/scene_name_casing" type="int" setter="" getter="" default="2"> - When generating file names from scene root node, set the type of casing in this project. This is mostly an editor setting. + When generating scene file names from scene root node, set the type of casing to use in this project. This is mostly an editor setting. + </member> + <member name="editor/naming/script_name_casing" type="int" setter="" getter="" default="0"> + When generating script file names from the selected node, set the type of casing to use in this project. This is mostly an editor setting. </member> <member name="editor/run/main_run_args" type="String" setter="" getter="" default=""""> The command-line arguments to append to Godot's own command line when running the project. This doesn't affect the editor itself. It is possible to make another executable run Godot by using the [code]%command%[/code] placeholder. The placeholder will be replaced with Godot's own command line. Program-specific arguments should be placed [i]before[/i] the placeholder, whereas Godot-specific arguments should be placed [i]after[/i] the placeholder. - For example, this can be used to force the project to run on the dedicated GPU in a NVIDIA Optimus system on Linux: + For example, this can be used to force the project to run on the dedicated GPU in an NVIDIA Optimus system on Linux: [codeblock] prime-run %command% [/codeblock] @@ -939,7 +980,7 @@ </member> <member name="filesystem/import/blender/enabled" type="bool" setter="" getter="" default="true"> If [code]true[/code], Blender 3D scene files with the [code].blend[/code] extension will be imported by converting them to glTF 2.0. - This requires configuring a path to a Blender executable in the editor settings at [code]filesystem/import/blender/blender3_path[/code]. Blender 3.0 or later is required. + This requires configuring a path to a Blender executable in the editor settings at [code]filesystem/import/blender/blender_path[/code]. Blender 3.0 or later is required. </member> <member name="filesystem/import/blender/enabled.android" type="bool" setter="" getter="" default="false"> Override for [member filesystem/import/blender/enabled] on Android where Blender can't easily be accessed from Godot. @@ -947,15 +988,15 @@ <member name="filesystem/import/blender/enabled.web" type="bool" setter="" getter="" default="false"> Override for [member filesystem/import/blender/enabled] on the Web where Blender can't easily be accessed from Godot. </member> - <member name="filesystem/import/fbx/enabled" type="bool" setter="" getter="" default="true"> + <member name="filesystem/import/fbx2gltf/enabled" type="bool" setter="" getter="" default="true"> If [code]true[/code], Autodesk FBX 3D scene files with the [code].fbx[/code] extension will be imported by converting them to glTF 2.0. - This requires configuring a path to a FBX2glTF executable in the editor settings at [code]filesystem/import/fbx/fbx2gltf_path[/code]. + This requires configuring a path to an FBX2glTF executable in the editor settings at [member EditorSettings.filesystem/import/fbx2gltf/fbx2gltf_path]. </member> - <member name="filesystem/import/fbx/enabled.android" type="bool" setter="" getter="" default="false"> - Override for [member filesystem/import/fbx/enabled] on Android where FBX2glTF can't easily be accessed from Godot. + <member name="filesystem/import/fbx2gltf/enabled.android" type="bool" setter="" getter="" default="false"> + Override for [member filesystem/import/fbx2gltf/enabled] on Android where FBX2glTF can't easily be accessed from Godot. </member> - <member name="filesystem/import/fbx/enabled.web" type="bool" setter="" getter="" default="false"> - Override for [member filesystem/import/fbx/enabled] on the Web where FBX2glTF can't easily be accessed from Godot. + <member name="filesystem/import/fbx2gltf/enabled.web" type="bool" setter="" getter="" default="false"> + Override for [member filesystem/import/fbx2gltf/enabled] on the Web where FBX2glTF can't easily be accessed from Godot. </member> <member name="gui/common/default_scroll_deadzone" type="int" setter="" getter="" default="0"> Default value for [member ScrollContainer.scroll_deadzone], which will be used for all [ScrollContainer]s unless overridden. @@ -1108,7 +1149,7 @@ [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. </member> <member name="input/ui_swap_input_direction" type="Dictionary" setter="" getter=""> - Default [InputEventAction] to swap input direction, i.e. change between left-to-right to right-to-left modes. Affects text-editting controls ([LineEdit], [TextEdit]). + Default [InputEventAction] to swap input direction, i.e. change between left-to-right to right-to-left modes. Affects text-editing controls ([LineEdit], [TextEdit]). </member> <member name="input/ui_text_add_selection_for_next_occurrence" type="Dictionary" setter="" getter=""> If a selection is currently active with the last caret in text fields, searches for the next occurrence of the selection, adds a caret and selects the next occurrence. @@ -1219,15 +1260,15 @@ [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. </member> <member name="input/ui_text_completion_accept" type="Dictionary" setter="" getter=""> - Default [InputEventAction] to accept an autocompetion hint. + Default [InputEventAction] to accept an autocompletion hint. [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. </member> <member name="input/ui_text_completion_query" type="Dictionary" setter="" getter=""> - Default [InputEventAction] to request autocompetion. + Default [InputEventAction] to request autocompletion. [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. </member> <member name="input/ui_text_completion_replace" type="Dictionary" setter="" getter=""> - Default [InputEventAction] to accept an autocompetion hint, replacing existing text. + Default [InputEventAction] to accept an autocompletion hint, replacing existing text. [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. </member> <member name="input/ui_text_dedent" type="Dictionary" setter="" getter=""> @@ -1293,6 +1334,12 @@ <member name="input/ui_text_select_word_under_caret.macos" type="Dictionary" setter="" getter=""> macOS specific override for the shortcut to select the word currently under the caret. </member> + <member name="input/ui_text_skip_selection_for_next_occurrence" type="Dictionary" setter="" getter=""> + If no selection is currently active with the last caret in text fields, searches for the next occurrence of the the word currently under the caret and moves the caret to the next occurrence. The action can be performed sequentially for other occurrences of the word under the last caret. + If a selection is currently active with the last caret in text fields, searches for the next occurrence of the selection, adds a caret, selects the next occurrence then deselects the previous selection and its associated caret. The action can be performed sequentially for other occurrences of the selection of the last caret. + The viewport is adjusted to the latest newly added caret. + [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. + </member> <member name="input/ui_text_submit" type="Dictionary" setter="" getter=""> Default [InputEventAction] to submit a text field. [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. @@ -1333,6 +1380,9 @@ <member name="input_devices/pointing/android/enable_pan_and_scale_gestures" type="bool" setter="" getter="" default="false"> If [code]true[/code], multi-touch pan and scale gestures are enabled on Android devices. </member> + <member name="input_devices/pointing/android/rotary_input_scroll_axis" type="int" setter="" getter="" default="1"> + On Wear OS devices, defines which axis of the mouse wheel rotary input is mapped to. This rotary input is usually performed by rotating the physical or virtual (touch-based) bezel on a smartwatch. + </member> <member name="input_devices/pointing/emulate_mouse_from_touch" type="bool" setter="" getter="" default="true"> If [code]true[/code], sends mouse input events when tapping or swiping on the touchscreen. </member> @@ -1386,7 +1436,7 @@ </member> <member name="internationalization/rendering/text_driver" type="String" setter="" getter="" default=""""> Specifies the [TextServer] to use. If left empty, the default will be used. - "ICU / HarfBuzz / Graphite" is the most advanced text driver, supporting right-to-left typesetting and complex scripts (for languages like Arabic, Hebrew, etc). The "Fallback" text driver does not support right-to-left typesetting and complex scripts. + "ICU / HarfBuzz / Graphite" is the most advanced text driver, supporting right-to-left typesetting and complex scripts (for languages like Arabic, Hebrew, etc.). The "Fallback" text driver does not support right-to-left typesetting and complex scripts. [b]Note:[/b] The driver in use can be overridden at runtime via the [code]--text-driver[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. [b]Note:[/b] There is an additional [code]Dummy[/code] text driver available, which disables all text rendering and font-related functionality. This driver is not listed in the project settings, but it can be enabled when running the editor or project using the [code]--text-driver Dummy[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. </member> @@ -1993,9 +2043,6 @@ <member name="memory/limits/message_queue/max_size_mb" type="int" setter="" getter="" default="32"> Godot uses a message queue to defer some function calls. If you run out of space on it (you will see an error), you can increase the size here. </member> - <member name="memory/limits/multithreaded_server/rid_pool_prealloc" type="int" setter="" getter="" default="60"> - This is used by servers when used in multi-threading mode (servers and visual). RIDs are preallocated to avoid stalling the server requesting them on threads. If servers get stalled too often when loading resources in a thread, increase this number. - </member> <member name="navigation/2d/default_cell_size" type="float" setter="" getter="" default="1.0"> Default cell size for 2D navigation maps. See [method NavigationServer2D.map_set_cell_size]. </member> @@ -2023,6 +2070,9 @@ <member name="navigation/3d/default_up" type="Vector3" setter="" getter="" default="Vector3(0, 1, 0)"> Default up orientation for 3D navigation maps. See [method NavigationServer3D.map_set_up]. </member> + <member name="navigation/3d/merge_rasterizer_cell_scale" type="float" setter="" getter="" default="1.0"> + Default merge rasterizer cell scale for 3D navigation maps. See [method NavigationServer3D.map_set_merge_rasterizer_cell_scale]. + </member> <member name="navigation/3d/use_edge_connections" type="bool" setter="" getter="" default="true"> If enabled 3D navigation regions will use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin. This setting only affects World3D default navigation maps. </member> @@ -2038,6 +2088,9 @@ <member name="navigation/baking/thread_model/baking_use_multiple_threads" type="bool" setter="" getter="" default="true"> If enabled the async navmesh baking uses multiple threads. </member> + <member name="navigation/baking/use_crash_prevention_checks" type="bool" setter="" getter="" default="true"> + If enabled, and baking would potentially lead to an engine crash, the baking will be interrupted and an error message with explanation will be raised. + </member> <member name="network/limits/debugger/max_chars_per_second" type="int" setter="" getter="" default="32768"> Maximum number of characters allowed to send as output from the debugger. Over this value, content is dropped. This helps not to stall the debugger connection. </member> @@ -2064,8 +2117,11 @@ If in doubt, leave this setting empty. </member> <member name="physics/2d/default_angular_damp" type="float" setter="" getter="" default="1.0"> - The default angular damp in 2D. - [b]Note:[/b] Good values are in the range [code]0[/code] to [code]1[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Values greater than [code]1[/code] will aim to reduce the velocity to [code]0[/code] in less than a second e.g. a value of [code]2[/code] will aim to reduce the velocity to [code]0[/code] in half a second. A value equal to or greater than the physics frame rate ([member ProjectSettings.physics/common/physics_ticks_per_second], [code]60[/code] by default) will bring the object to a stop in one iteration. + The default rotational motion damping in 2D. Damping is used to gradually slow down physical objects over time. RigidBodies will fall back to this value when combining their own damping values and no area damping value is present. + Suggested values are in the range [code]0[/code] to [code]30[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Greater values will stop the object faster. A value equal to or greater than the physics tick rate ([member physics/common/physics_ticks_per_second]) will bring the object to a stop in one iteration. + [b]Note:[/b] Godot damping calculations are velocity-dependent, meaning bodies moving faster will take a longer time to come to rest. They do not simulate inertia, friction, or air resistance. Therefore heavier or larger bodies will lose speed at the same proportional rate as lighter or smaller bodies. + During each physics tick, Godot will multiply the linear velocity of RigidBodies by [code]1.0 - combined_damp / physics_ticks_per_second[/code]. By default, bodies combine damp factors: [code]combined_damp[/code] is the sum of the damp value of the body and this value or the area's value the body is in. See [enum RigidBody2D.DampMode]. + [b]Warning:[/b] Godot's damping calculations are simulation tick rate dependent. Changing [member physics/common/physics_ticks_per_second] may significantly change the outcomes and feel of your simulation. This is true for the entire range of damping values greater than 0. To get back to a similar feel, you also need to change your damp values. This needed change is not proportional and differs from case to case. </member> <member name="physics/2d/default_gravity" type="float" setter="" getter="" default="980.0"> The default gravity strength in 2D (in pixels per second squared). @@ -2096,8 +2152,11 @@ [/codeblocks] </member> <member name="physics/2d/default_linear_damp" type="float" setter="" getter="" default="0.1"> - The default linear damp in 2D. - [b]Note:[/b] Good values are in the range [code]0[/code] to [code]1[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Values greater than [code]1[/code] will aim to reduce the velocity to [code]0[/code] in less than a second e.g. a value of [code]2[/code] will aim to reduce the velocity to [code]0[/code] in half a second. A value equal to or greater than the physics frame rate ([member ProjectSettings.physics/common/physics_ticks_per_second], [code]60[/code] by default) will bring the object to a stop in one iteration. + The default linear motion damping in 2D. Damping is used to gradually slow down physical objects over time. RigidBodies will fall back to this value when combining their own damping values and no area damping value is present. + Suggested values are in the range [code]0[/code] to [code]30[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Greater values will stop the object faster. A value equal to or greater than the physics tick rate ([member physics/common/physics_ticks_per_second]) will bring the object to a stop in one iteration. + [b]Note:[/b] Godot damping calculations are velocity-dependent, meaning bodies moving faster will take a longer time to come to rest. They do not simulate inertia, friction, or air resistance. Therefore heavier or larger bodies will lose speed at the same proportional rate as lighter or smaller bodies. + During each physics tick, Godot will multiply the linear velocity of RigidBodies by [code]1.0 - combined_damp / physics_ticks_per_second[/code], where [code]combined_damp[/code] is the sum of the linear damp of the body and this value, or the area's value the body is in, assuming the body defaults to combine damp values. See [enum RigidBody2D.DampMode]. + [b]Warning:[/b] Godot's damping calculations are simulation tick rate dependent. Changing [member physics/common/physics_ticks_per_second] may significantly change the outcomes and feel of your simulation. This is true for the entire range of damping values greater than 0. To get back to a similar feel, you also need to change your damp values. This needed change is not proportional and differs from case to case. </member> <member name="physics/2d/physics_engine" type="String" setter="" getter="" default=""DEFAULT""> Sets which physics engine to use for 2D physics. @@ -2136,8 +2195,11 @@ Time (in seconds) of inactivity before which a 2D physics body will put to sleep. See [constant PhysicsServer2D.SPACE_PARAM_BODY_TIME_TO_SLEEP]. </member> <member name="physics/3d/default_angular_damp" type="float" setter="" getter="" default="0.1"> - The default angular damp in 3D. - [b]Note:[/b] Good values are in the range [code]0[/code] to [code]1[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Values greater than [code]1[/code] will aim to reduce the velocity to [code]0[/code] in less than a second e.g. a value of [code]2[/code] will aim to reduce the velocity to [code]0[/code] in half a second. A value equal to or greater than the physics frame rate ([member ProjectSettings.physics/common/physics_ticks_per_second], [code]60[/code] by default) will bring the object to a stop in one iteration. + The default rotational motion damping in 3D. Damping is used to gradually slow down physical objects over time. RigidBodies will fall back to this value when combining their own damping values and no area damping value is present. + Suggested values are in the range [code]0[/code] to [code]30[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Greater values will stop the object faster. A value equal to or greater than the physics tick rate ([member physics/common/physics_ticks_per_second]) will bring the object to a stop in one iteration. + [b]Note:[/b] Godot damping calculations are velocity-dependent, meaning bodies moving faster will take a longer time to come to rest. They do not simulate inertia, friction, or air resistance. Therefore heavier or larger bodies will lose speed at the same proportional rate as lighter or smaller bodies. + During each physics tick, Godot will multiply the angular velocity of RigidBodies by [code]1.0 - combined_damp / physics_ticks_per_second[/code]. By default, bodies combine damp factors: [code]combined_damp[/code] is the sum of the damp value of the body and this value or the area's value the body is in. See [enum RigidBody3D.DampMode]. + [b]Warning:[/b] Godot's damping calculations are simulation tick rate dependent. Changing [member physics/common/physics_ticks_per_second] may significantly change the outcomes and feel of your simulation. This is true for the entire range of damping values greater than 0. To get back to a similar feel, you also need to change your damp values. This needed change is not proportional and differs from case to case. </member> <member name="physics/3d/default_gravity" type="float" setter="" getter="" default="9.8"> The default gravity strength in 3D (in meters per second squared). @@ -2168,8 +2230,11 @@ [/codeblocks] </member> <member name="physics/3d/default_linear_damp" type="float" setter="" getter="" default="0.1"> - The default linear damp in 3D. - [b]Note:[/b] Good values are in the range [code]0[/code] to [code]1[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Values greater than [code]1[/code] will aim to reduce the velocity to [code]0[/code] in less than a second e.g. a value of [code]2[/code] will aim to reduce the velocity to [code]0[/code] in half a second. A value equal to or greater than the physics frame rate ([member ProjectSettings.physics/common/physics_ticks_per_second], [code]60[/code] by default) will bring the object to a stop in one iteration. + The default linear motion damping in 3D. Damping is used to gradually slow down physical objects over time. RigidBodies will fall back to this value when combining their own damping values and no area damping value is present. + Suggested values are in the range [code]0[/code] to [code]30[/code]. At value [code]0[/code] objects will keep moving with the same velocity. Greater values will stop the object faster. A value equal to or greater than the physics tick rate ([member physics/common/physics_ticks_per_second]) will bring the object to a stop in one iteration. + [b]Note:[/b] Godot damping calculations are velocity-dependent, meaning bodies moving faster will take a longer time to come to rest. They do not simulate inertia, friction, or air resistance. Therefore heavier or larger bodies will lose speed at the same proportional rate as lighter or smaller bodies. + During each physics tick, Godot will multiply the linear velocity of RigidBodies by [code]1.0 - combined_damp / physics_ticks_per_second[/code]. By default, bodies combine damp factors: [code]combined_damp[/code] is the sum of the damp value of the body and this value or the area's value the body is in. See [enum RigidBody3D.DampMode]. + [b]Warning:[/b] Godot's damping calculations are simulation tick rate dependent. Changing [member physics/common/physics_ticks_per_second] may significantly change the outcomes and feel of your simulation. This is true for the entire range of damping values greater than 0. To get back to a similar feel, you also need to change your damp values. This needed change is not proportional and differs from case to case. </member> <member name="physics/3d/physics_engine" type="String" setter="" getter="" default=""DEFAULT""> Sets which physics engine to use for 3D physics. @@ -2210,9 +2275,15 @@ Controls the maximum number of physics steps that can be simulated each rendered frame. The default value is tuned to avoid "spiral of death" situations where expensive physics simulations trigger more expensive simulations indefinitely. However, the game will appear to slow down if the rendering FPS is less than [code]1 / max_physics_steps_per_frame[/code] of [member physics/common/physics_ticks_per_second]. This occurs even if [code]delta[/code] is consistently used in physics calculations. To avoid this, increase [member physics/common/max_physics_steps_per_frame] if you have increased [member physics/common/physics_ticks_per_second] significantly above its default value. [b]Note:[/b] This property is only read when the project starts. To change the maximum number of simulated physics steps per frame at runtime, set [member Engine.max_physics_steps_per_frame] instead. </member> + <member name="physics/common/physics_interpolation" type="bool" setter="" getter="" default="false"> + If [code]true[/code], the renderer will interpolate the transforms of physics objects between the last two transforms, so that smooth motion is seen even when physics ticks do not coincide with rendered frames. See also [member Node.physics_interpolation_mode] and [method Node.reset_physics_interpolation]. + [b]Note:[/b] If [code]true[/code], the physics jitter fix should be disabled by setting [member physics/common/physics_jitter_fix] to [code]0.0[/code]. + [b]Note:[/b] This property is only read when the project starts. To toggle physics interpolation at runtime, set [member SceneTree.physics_interpolation] instead. + [b]Note:[/b] This feature is currently only implemented in the 2D renderer. + </member> <member name="physics/common/physics_jitter_fix" type="float" setter="" getter="" default="0.5"> - Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of in-game clock and real clock, but allows smoothing out framerate jitters. The default value of 0.5 should be fine for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. - [b]Note:[/b] For best results, when using a custom physics interpolation solution, the physics jitter fix should be disabled by setting [member physics/common/physics_jitter_fix] to [code]0[/code]. + Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of in-game clock and real clock, but allows smoothing out framerate jitters. The default value of 0.5 should be good enough for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. + [b]Note:[/b] When using a physics interpolation solution (such as enabling [member physics/common/physics_interpolation] or using a custom solution), the physics jitter fix should be disabled by setting [member physics/common/physics_jitter_fix] to [code]0.0[/code]. [b]Note:[/b] This property is only read when the project starts. To change the physics jitter fix at runtime, set [member Engine.physics_jitter_fix] instead. </member> <member name="physics/common/physics_ticks_per_second" type="int" setter="" getter="" default="60"> @@ -2234,14 +2305,16 @@ [b]Note:[/b] This property is only read when the project starts. To change the 2D shadow atlas size at runtime, use [method RenderingServer.canvas_set_shadow_texture_size] instead. </member> <member name="rendering/2d/snap/snap_2d_transforms_to_pixel" type="bool" setter="" getter="" default="false"> - If [code]true[/code], [CanvasItem] nodes will internally snap to full pixels. Their position can still be sub-pixel, but the decimals will not have effect. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. + If [code]true[/code], [CanvasItem] nodes will internally snap to full pixels. Useful for low-resolution pixel art games. Their position can still be sub-pixel, but the decimals will not have effect as the position is rounded. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. [b]Note:[/b] This property is only read when the project starts. To toggle 2D transform snapping at runtime, use [method RenderingServer.viewport_set_snap_2d_transforms_to_pixel] on the root [Viewport] instead. [b]Note:[/b] [Control] nodes are snapped to the nearest pixel by default. This is controlled by [member gui/common/snap_controls_to_pixels]. + [b]Note:[/b] It is not recommended to use this setting together with [member rendering/2d/snap/snap_2d_vertices_to_pixel], as movement may appear even less smooth. Prefer only enabling this setting instead. </member> <member name="rendering/2d/snap/snap_2d_vertices_to_pixel" type="bool" setter="" getter="" default="false"> - If [code]true[/code], vertices of [CanvasItem] nodes will snap to full pixels. Only affects the final vertex positions, not the transforms. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. + If [code]true[/code], vertices of [CanvasItem] nodes will snap to full pixels. Useful for low-resolution pixel art games. Only affects the final vertex positions, not the transforms. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. [b]Note:[/b] This property is only read when the project starts. To toggle 2D vertex snapping at runtime, use [method RenderingServer.viewport_set_snap_2d_vertices_to_pixel] on the root [Viewport] instead. [b]Note:[/b] [Control] nodes are snapped to the nearest pixel by default. This is controlled by [member gui/common/snap_controls_to_pixels]. + [b]Note:[/b] It is not recommended to use this setting together with [member rendering/2d/snap/snap_2d_transforms_to_pixel], as movement may appear even less smooth. Prefer only enabling that setting instead. </member> <member name="rendering/anti_aliasing/quality/msaa_2d" type="int" setter="" getter="" default="0"> Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. This has no effect on shader-induced aliasing or texture aliasing. @@ -2293,9 +2366,8 @@ If [code]true[/code], performs a previous depth pass before rendering 3D materials. This increases performance significantly in scenes with high overdraw, when complex materials and lighting are used. However, in scenes with few occluded surfaces, the depth prepass may reduce performance. If your game is viewed from a fixed angle that makes it easy to avoid overdraw (such as top-down or side-scrolling perspective), consider disabling the depth prepass to improve performance. This setting can be changed at run-time to optimize performance depending on the scene currently being viewed. [b]Note:[/b] Depth prepass is only supported when using the Forward+ or Compatibility rendering method. When using the Mobile rendering method, there is no depth prepass performed. </member> - <member name="rendering/driver/threads/thread_model" type="int" setter="" getter="" default="1"> + <member name="rendering/driver/threads/thread_model" type="int" setter="" getter="" default="1" experimental="This setting has several known bugs which can lead to crashing, especially when using particles or resizing the window. Not recommended for use in production at this stage."> The thread model to use for rendering. Rendering on a thread may improve performance, but synchronizing to the main thread can cause a bit more jitter. - [b]Note:[/b] The [b]Multi-Threaded[/b] option is experimental, and has several known bugs which can lead to crashing, especially when using particles or resizing the window. Not recommended for use in production at this stage. </member> <member name="rendering/environment/defaults/default_clear_color" type="Color" setter="" getter="" default="Color(0.3, 0.3, 0.3, 1)"> Default background clear color. Overridable per [Viewport] using its [Environment]. See [member Environment.background_mode] and [member Environment.background_color] in particular. To change this default color programmatically, use [method RenderingServer.set_default_clear_color]. @@ -2529,6 +2601,10 @@ <member name="rendering/lights_and_shadows/positional_shadow/soft_shadow_filter_quality.mobile" type="int" setter="" getter="" default="0"> Lower-end override for [member rendering/lights_and_shadows/positional_shadow/soft_shadow_filter_quality] on mobile devices, due to performance concerns or driver support. </member> + <member name="rendering/lights_and_shadows/tighter_shadow_caster_culling" type="bool" setter="" getter="" default="true"> + If [code]true[/code], items that cannot cast shadows into the view frustum will not be rendered into shadow maps. + This can increase performance. + </member> <member name="rendering/lights_and_shadows/use_physical_light_units" type="bool" setter="" getter="" default="false"> Enables the use of physically based units for light sources. Physically based units tend to be much larger than the arbitrary units used by Godot, but they can be used to match lighting within Godot to real-world lighting. Due to the large dynamic range of lighting conditions present in nature, Godot bakes exposure into the various lighting quantities before rendering. Most light sources bake exposure automatically at run time based on the active [CameraAttributes] resource, but [LightmapGI] and [VoxelGI] require a [CameraAttributes] resource to be set at bake time to reduce the dynamic range. At run time, Godot will automatically reconcile the baked exposure with the active exposure to ensure lighting remains consistent. </member> @@ -2537,8 +2613,6 @@ Decreasing this value may improve GPU performance on certain setups, even if the maximum number of clustered elements is never reached in the project. [b]Note:[/b] This setting is only effective when using the Forward+ rendering method, not Mobile and Compatibility. </member> - <member name="rendering/limits/forward_renderer/threaded_render_minimum_instances" type="int" setter="" getter="" default="500"> - </member> <member name="rendering/limits/global_shader_variables/buffer_size" type="int" setter="" getter="" default="65536"> </member> <member name="rendering/limits/opengl/max_lights_per_object" type="int" setter="" getter="" default="8"> @@ -2554,6 +2628,7 @@ [b]Note:[/b] This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. </member> <member name="rendering/limits/spatial_indexer/threaded_cull_minimum_instances" type="int" setter="" getter="" default="1000"> + The minimum number of instances that must be present in a scene to enable culling computations on multiple threads. If a scene has fewer instances than this number, culling is done on a single thread. </member> <member name="rendering/limits/spatial_indexer/update_iterations_per_frame" type="int" setter="" getter="" default="10"> </member> @@ -2568,6 +2643,9 @@ The [url=https://en.wikipedia.org/wiki/Bounding_volume_hierarchy]Bounding Volume Hierarchy[/url] quality to use when rendering the occlusion culling buffer. Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. See also [member rendering/occlusion_culling/occlusion_rays_per_thread]. [b]Note:[/b] This property is only read when the project starts. To adjust the BVH build quality at runtime, use [method RenderingServer.viewport_set_occlusion_culling_build_quality]. </member> + <member name="rendering/occlusion_culling/jitter_projection" type="bool" setter="" getter="" default="true"> + If [code]true[/code], the projection used for rendering the occlusion buffer will be jittered. This can help prevent objects being incorrectly culled when visible through small gaps. + </member> <member name="rendering/occlusion_culling/occlusion_rays_per_thread" type="int" setter="" getter="" default="512"> The number of occlusion rays traced per CPU thread. Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. The occlusion culling buffer's pixel count is roughly equal to [code]occlusion_rays_per_thread * number_of_logical_cpu_cores[/code], so it will depend on the system's CPU. Therefore, CPUs with fewer cores will use a lower resolution to attempt keeping performance costs even across devices. See also [member rendering/occlusion_culling/bvh_build_quality]. [b]Note:[/b] This property is only read when the project starts. To adjust the number of occlusion rays traced per thread at runtime, use [method RenderingServer.viewport_set_occlusion_rays_per_thread]. @@ -2616,6 +2694,21 @@ <member name="rendering/renderer/rendering_method.web" type="String" setter="" getter="" default=""gl_compatibility""> Override for [member rendering/renderer/rendering_method] on web. </member> + <member name="rendering/rendering_device/d3d12/agility_sdk_version" type="int" setter="" getter="" default="610"> + Version code of the Direct3D 12 Agility SDK to use ([code]D3D12SDKVersion[/code]). + </member> + <member name="rendering/rendering_device/d3d12/max_misc_descriptors_per_frame" type="int" setter="" getter="" default="512"> + The number of entries in the miscellaneous descriptors heap the Direct3D 12 rendering driver uses each frame, used for various operations like clearing a texture. + Depending on the complexity of scenes, this value may be lowered or may need to be raised. + </member> + <member name="rendering/rendering_device/d3d12/max_resource_descriptors_per_frame" type="int" setter="" getter="" default="16384"> + The number of entries in the resource descriptors heap the Direct3D 12 rendering driver uses each frame, used for most rendering operations. + Depending on the complexity of scenes, this value may be lowered or may need to be raised. + </member> + <member name="rendering/rendering_device/d3d12/max_sampler_descriptors_per_frame" type="int" setter="" getter="" default="1024"> + The number of entries in the sampler descriptors heap the Direct3D 12 rendering driver uses each frame, used for most rendering operations. + Depending on the complexity of scenes, this value may be lowered or may need to be raised. + </member> <member name="rendering/rendering_device/driver" type="String" setter="" getter=""> Sets the driver to be used by the renderer when using a RenderingDevice-based renderer like the clustered renderer or the mobile renderer. This property can not be edited directly, instead, set the driver using the platform-specific overrides. </member> @@ -2634,6 +2727,10 @@ <member name="rendering/rendering_device/driver.windows" type="String" setter="" getter=""> Windows override for [member rendering/rendering_device/driver]. </member> + <member name="rendering/rendering_device/pipeline_cache/enable" type="bool" setter="" getter="" default="true"> + Enable the pipeline cache that is saved to disk if the graphics API supports it. + [b]Note:[/b] This property is unable to control the pipeline caching the GPU driver itself does. Only turn this off along with deleting the contents of the driver's cache if you wish to simulate the experience a user will get when starting the game for the first time. + </member> <member name="rendering/rendering_device/pipeline_cache/save_chunk_size_mb" type="float" setter="" getter="" default="3.0"> Determines at which interval pipeline cache is saved to disk. The lower the value, the more often it is saved. </member> @@ -2643,6 +2740,20 @@ </member> <member name="rendering/rendering_device/staging_buffer/texture_upload_region_size_px" type="int" setter="" getter="" default="64"> </member> + <member name="rendering/rendering_device/vsync/frame_queue_size" type="int" setter="" getter="" default="2"> + The number of frames to track on the CPU side before stalling to wait for the GPU. + Try the [url=https://darksylinc.github.io/vsync_simulator/]V-Sync Simulator[/url], an interactive interface that simulates presentation to better understand how it is affected by different variables under various conditions. + [b]Note:[/b] This property is only read when the project starts. There is currently no way to change this value at run-time. + </member> + <member name="rendering/rendering_device/vsync/swapchain_image_count" type="int" setter="" getter="" default="3"> + The number of images the swapchain will consist of (back buffers + front buffer). + [code]2[/code] corresponds to double-buffering and [code]3[/code] to triple-buffering. + Double-buffering may give you the lowest lag/latency but if V-Sync is on and the system can't render at 60 fps, the framerate will go down in multiples of it (e.g. 30 fps, 15, 7.5, etc.). Triple buffering gives you higher framerate (specially if the system can't reach a constant 60 fps) at the cost of up to 1 frame of latency, with [constant DisplayServer.VSYNC_ENABLED] (FIFO). + Use double-buffering with [constant DisplayServer.VSYNC_ENABLED]. Triple-buffering is a must if you plan on using [constant DisplayServer.VSYNC_MAILBOX] mode. + Try the [url=https://darksylinc.github.io/vsync_simulator/]V-Sync Simulator[/url], an interactive interface that simulates presentation to better understand how it is affected by different variables under various conditions. + [b]Note:[/b] This property is only read when the project starts. There is currently no way to change this value at run-time. + [b]Note:[/b] Some platforms may restrict the actual value. + </member> <member name="rendering/rendering_device/vulkan/max_descriptors_per_pool" type="int" setter="" getter="" default="64"> </member> <member name="rendering/scaling_3d/fsr_sharpness" type="float" setter="" getter="" default="0.2"> @@ -2682,6 +2793,7 @@ </member> <member name="rendering/textures/canvas_textures/default_texture_filter" type="int" setter="" getter="" default="1"> The default texture filtering mode to use on [CanvasItem]s. + [b]Note:[/b] For pixel art aesthetics, see also [member rendering/2d/snap/snap_2d_vertices_to_pixel] and [member rendering/2d/snap/snap_2d_transforms_to_pixel]. </member> <member name="rendering/textures/canvas_textures/default_texture_repeat" type="int" setter="" getter="" default="0"> The default texture repeating mode to use on [CanvasItem]s. @@ -2711,7 +2823,7 @@ If [code]true[/code], the texture importer will import lossless textures using the PNG format. Otherwise, it will default to using WebP. </member> <member name="rendering/textures/vram_compression/import_etc2_astc" type="bool" setter="" getter="" default="false"> - If [code]true[/code], the texture importer will import VRAM-compressed textures using the Ericsson Texture Compression 2 algorithm for lower quality textures and normal maps and Adaptable Scalable Texture Compression algorithm for high quality textures (in 4x4 block size). + If [code]true[/code], the texture importer will import VRAM-compressed textures using the Ericsson Texture Compression 2 algorithm for lower quality textures and normal maps and Adaptable Scalable Texture Compression algorithm for high quality textures (in 4×4 block size). [b]Note:[/b] This setting is an override. The texture importer will always import the format the host platform needs, even if this is set to [code]false[/code]. [b]Note:[/b] Changing this setting does [i]not[/i] impact textures that were already imported before. To make this setting apply to textures that were already imported, exit the editor, remove the [code].godot/imported/[/code] folder located inside the project folder then restart the editor (see [member application/config/use_hidden_project_data_directory]). </member> @@ -2739,30 +2851,29 @@ If [member rendering/vrs/mode] is set to [b]Texture[/b], this is the path to default texture loaded as the VRS image. The texture [i]must[/i] use a lossless compression format so that colors can be matched precisely. The following VRS densities are mapped to various colors, with brighter colors representing a lower level of shading precision: [codeblock] - - 1x1 = rgb(0, 0, 0) - #000000 - - 1x2 = rgb(0, 85, 0) - #005500 - - 2x1 = rgb(85, 0, 0) - #550000 - - 2x2 = rgb(85, 85, 0) - #555500 - - 2x4 = rgb(85, 170, 0) - #55aa00 - - 4x2 = rgb(170, 85, 0) - #aa5500 - - 4x4 = rgb(170, 170, 0) - #aaaa00 - - 4x8 = rgb(170, 255, 0) - #aaff00 - Not supported on most hardware - - 8x4 = rgb(255, 170, 0) - #ffaa00 - Not supported on most hardware - - 8x8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware + - 1×1 = rgb(0, 0, 0) - #000000 + - 1×2 = rgb(0, 85, 0) - #005500 + - 2×1 = rgb(85, 0, 0) - #550000 + - 2×2 = rgb(85, 85, 0) - #555500 + - 2×4 = rgb(85, 170, 0) - #55aa00 + - 4×2 = rgb(170, 85, 0) - #aa5500 + - 4×4 = rgb(170, 170, 0) - #aaaa00 + - 4×8 = rgb(170, 255, 0) - #aaff00 - Not supported on most hardware + - 8×4 = rgb(255, 170, 0) - #ffaa00 - Not supported on most hardware + - 8×8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware [/codeblock] </member> <member name="threading/worker_pool/low_priority_thread_ratio" type="float" setter="" getter="" default="0.3"> + The ratio of [WorkerThreadPool]'s threads that will be reserved for low-priority tasks. For example, if 10 threads are available and this value is set to [code]0.3[/code], 3 of the worker threads will be reserved for low-priority tasks. The actual value won't exceed the number of CPU cores minus one, and if possible, at least one worker thread will be dedicated to low-priority tasks. </member> <member name="threading/worker_pool/max_threads" type="int" setter="" getter="" default="-1"> Maximum number of threads to be used by [WorkerThreadPool]. Value of [code]-1[/code] means no limit. </member> - <member name="threading/worker_pool/use_system_threads_for_low_priority_tasks" type="bool" setter="" getter="" default="true"> - </member> <member name="xr/openxr/default_action_map" type="String" setter="" getter="" default=""res://openxr_action_map.tres""> Action map configuration to load by default. </member> <member name="xr/openxr/enabled" type="bool" setter="" getter="" default="false"> - If [code]true[/code] Godot will setup and initialize OpenXR on startup. + If [code]true[/code], Godot will setup and initialize OpenXR on startup. </member> <member name="xr/openxr/environment_blend_mode" type="int" setter="" getter="" default=""0""> Specify how OpenXR should blend in the environment. This is specific to certain AR and passthrough devices where camera images are blended in by the XR compositor. @@ -2778,9 +2889,11 @@ </member> <member name="xr/openxr/foveation_dynamic" type="bool" setter="" getter="" default="false"> If true and foveation is supported, will automatically adjust foveation level based on framerate up to the level set on [member xr/openxr/foveation_level]. + [b]Note:[/b] Only works on compatibility renderer. </member> <member name="xr/openxr/foveation_level" type="int" setter="" getter="" default=""0""> Applied foveation level if supported: 0 = off, 1 = low, 2 = medium, 3 = high. + [b]Note:[/b] Only works on compatibility renderer. </member> <member name="xr/openxr/reference_space" type="int" setter="" getter="" default=""1""> Specify the default reference space. diff --git a/doc/classes/Projection.xml b/doc/classes/Projection.xml index 694556a693..1665660da3 100644 --- a/doc/classes/Projection.xml +++ b/doc/classes/Projection.xml @@ -4,7 +4,7 @@ A 4×4 matrix for 3D projective transformations. </brief_description> <description> - A 4x4 matrix used for 3D projective transformations. It can represent transformations such as translation, rotation, scaling, shearing, and perspective division. It consists of four [Vector4] columns. + A 4×4 matrix used for 3D projective transformations. It can represent transformations such as translation, rotation, scaling, shearing, and perspective division. It consists of four [Vector4] columns. For purely linear transformations (translation, rotation, and scale), it is recommended to use [Transform3D], as it is more performant and requires less memory. Used internally as [Camera3D]'s projection matrix. </description> diff --git a/doc/classes/PropertyTweener.xml b/doc/classes/PropertyTweener.xml index 73e594218d..d3875ddfc2 100644 --- a/doc/classes/PropertyTweener.xml +++ b/doc/classes/PropertyTweener.xml @@ -43,6 +43,25 @@ [/codeblock] </description> </method> + <method name="set_custom_interpolator"> + <return type="PropertyTweener" /> + <param index="0" name="interpolator_method" type="Callable" /> + <description> + Allows interpolating the value with a custom easing function. The provided [param interpolator_method] will be called with a value ranging from [code]0.0[/code] to [code]1.0[/code] and is expected to return a value within the same range (values outside the range can be used for overshoot). The return value of the method is then used for interpolation between initial and final value. Note that the parameter passed to the method is still subject to the tweener's own easing. + [b]Example:[/b] + [codeblock] + @export var curve: Curve + + func _ready(): + var tween = create_tween() + # Interpolate the value using a custom curve. + tween.tween_property(self, "position:x", 300, 1).as_relative().set_custom_interpolator(tween_curve) + + func tween_curve(v): + return curve.sample_baked(v) + [/codeblock] + </description> + </method> <method name="set_delay"> <return type="PropertyTweener" /> <param index="0" name="delay" type="float" /> diff --git a/doc/classes/Quaternion.xml b/doc/classes/Quaternion.xml index 74dfae77fc..8b59448555 100644 --- a/doc/classes/Quaternion.xml +++ b/doc/classes/Quaternion.xml @@ -4,19 +4,24 @@ A unit quaternion used for representing 3D rotations. </brief_description> <description> - Quaternions are similar to [Basis], which implements the matrix representation of rotations. Unlike [Basis], which stores rotation, scale, and shearing, quaternions only store rotation. - Quaternions can be parametrized using both an axis-angle pair or Euler angles. Due to their compactness and the way they are stored in memory, certain operations (obtaining axis-angle and performing SLERP, in particular) are more efficient and robust against floating-point errors. - [b]Note:[/b] Quaternions need to be normalized before being used for rotation. + The [Quaternion] built-in [Variant] type is a 4D data structure that represents rotation in the form of a [url=https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation]Hamilton convention quaternion[/url]. Compared to the [Basis] type which can store both rotation and scale, quaternions can [i]only[/i] store rotation. + A [Quaternion] is composed by 4 floating-point components: [member w], [member x], [member y], and [member z]. These components are very compact in memory, and because of this some operations are more efficient and less likely to cause floating-point errors. Methods such as [method get_angle], [method get_axis], and [method slerp] are faster than their [Basis] counterparts. + For a great introduction to quaternions, see [url=https://www.youtube.com/watch?v=d4EgbgTm0Bg]this video by 3Blue1Brown[/url]. You do not need to know the math behind quaternions, as Godot provides several helper methods that handle it for you. These include [method slerp] and [method spherical_cubic_interpolate], as well as the [code]*[/code] operator. + [b]Note:[/b] Quaternions must be normalized before being used for rotation (see [method normalized]). + [b]Note:[/b] Similarly to [Vector2] and [Vector3], the components of a quaternion use 32-bit precision by default, unlike [float] which is always 64-bit. If double precision is needed, compile the engine with the option [code]precision=double[/code]. </description> <tutorials> + <link title="3Blue1Brown's video on Quaternions">https://www.youtube.com/watch?v=d4EgbgTm0Bg</link> + <link title="Online Quaternion Visualization">https://quaternions.online/</link> <link title="Using 3D transforms">$DOCS_URL/tutorials/3d/using_transforms.html#interpolating-with-quaternions</link> <link title="Third Person Shooter Demo">https://godotengine.org/asset-library/asset/678</link> + <link title="Advanced Quaternion Visualization">https://iwatake2222.github.io/rotation_master/rotation_master.html</link> </tutorials> <constructors> <constructor name="Quaternion"> <return type="Quaternion" /> <description> - Constructs a default-initialized quaternion with all components set to [code]0[/code]. + Constructs a [Quaternion] identical to the [constant IDENTITY]. </description> </constructor> <constructor name="Quaternion"> @@ -31,7 +36,7 @@ <param index="0" name="arc_from" type="Vector3" /> <param index="1" name="arc_to" type="Vector3" /> <description> - Constructs a quaternion representing the shortest arc between two points on the surface of a sphere with a radius of [code]1.0[/code]. + Constructs a [Quaternion] representing the shortest arc between [param arc_from] and [param arc_to]. These can be imagined as two points intersecting a sphere's surface, with a radius of [code]1.0[/code]. </description> </constructor> <constructor name="Quaternion"> @@ -39,14 +44,15 @@ <param index="0" name="axis" type="Vector3" /> <param index="1" name="angle" type="float" /> <description> - Constructs a quaternion that will rotate around the given axis by the specified angle. The axis must be a normalized vector. + Constructs a [Quaternion] representing rotation around the [param axis] by the given [param angle], in radians. The axis must be a normalized vector. </description> </constructor> <constructor name="Quaternion"> <return type="Quaternion" /> <param index="0" name="from" type="Basis" /> <description> - Constructs a quaternion from the given [Basis]. + Constructs a [Quaternion] from the given rotation [Basis]. + This constructor is faster than [method Basis.get_rotation_quaternion], but the given basis must be [i]orthonormalized[/i] (see [method Basis.orthonormalized]). Otherwise, the constructor fails and returns [constant IDENTITY]. </description> </constructor> <constructor name="Quaternion"> @@ -56,7 +62,8 @@ <param index="2" name="z" type="float" /> <param index="3" name="w" type="float" /> <description> - Constructs a quaternion defined by the given values. + Constructs a [Quaternion] defined by the given values. + [b]Note:[/b] Only normalized quaternions represent rotation; if these values are not normalized, the new [Quaternion] will not be a valid rotation. </description> </constructor> </constructors> @@ -73,42 +80,48 @@ <return type="float" /> <param index="0" name="with" type="Quaternion" /> <description> - Returns the dot product of two quaternions. + Returns the dot product between this quaternion and [param with]. + This is equivalent to [code](quat.x * with.x) + (quat.y * with.y) + (quat.z * with.z) + (quat.w * with.w)[/code]. </description> </method> <method name="exp" qualifiers="const"> <return type="Quaternion" /> <description> + Returns the exponential of this quaternion. The rotation axis of the result is the normalized rotation axis of this quaternion, the angle of the result is the length of the vector part of this quaternion. </description> </method> <method name="from_euler" qualifiers="static"> <return type="Quaternion" /> <param index="0" name="euler" type="Vector3" /> <description> - Constructs a Quaternion from Euler angles in YXZ rotation order. + Constructs a new [Quaternion] from the given [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians. This method always uses the YXZ convention ([constant EULER_ORDER_YXZ]). </description> </method> <method name="get_angle" qualifiers="const"> <return type="float" /> <description> + Returns the angle of the rotation represented by this quaternion. + [b]Note:[/b] The quaternion must be normalized. </description> </method> <method name="get_axis" qualifiers="const"> <return type="Vector3" /> <description> + Returns the rotation axis of the rotation represented by this quaternion. </description> </method> <method name="get_euler" qualifiers="const"> <return type="Vector3" /> <param index="0" name="order" type="int" default="2" /> <description> - Returns the quaternion's rotation in the form of Euler angles. The Euler order depends on the [param order] parameter, for example using the YXZ convention: since this method decomposes, first Z, then X, and Y last. See the [enum EulerOrder] enum for possible values. The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle). + Returns this quaternion's rotation as a [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians. + The order of each consecutive rotation can be changed with [param order] (see [enum EulerOrder] constants). By default, the YXZ convention is used ([constant EULER_ORDER_YXZ]): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method [method from_euler], this order is reversed. </description> </method> <method name="inverse" qualifiers="const"> <return type="Quaternion" /> <description> - Returns the inverse of the quaternion. + Returns the inverse version of this quaternion, inverting the sign of every component except [member w]. </description> </method> <method name="is_equal_approx" qualifiers="const"> @@ -127,39 +140,40 @@ <method name="is_normalized" qualifiers="const"> <return type="bool" /> <description> - Returns whether the quaternion is normalized or not. + Returns [code]true[/code] if this quaternion is normalized. See also [method normalized]. </description> </method> - <method name="length" qualifiers="const"> + <method name="length" qualifiers="const" keywords="size"> <return type="float" /> <description> - Returns the length of the quaternion. + Returns this quaternion's length, also called magnitude. </description> </method> <method name="length_squared" qualifiers="const"> <return type="float" /> <description> - Returns the length of the quaternion, squared. + Returns this quaternion's length, squared. + [b]Note:[/b] This method is faster than [method length], so prefer it if you only need to compare quaternion lengths. </description> </method> <method name="log" qualifiers="const"> <return type="Quaternion" /> <description> + Returns the logarithm of this quaternion. Multiplies this quaternion's rotation axis by its rotation angle, and stores the result in the returned quaternion's vector part ([member x], [member y], and [member z]). The returned quaternion's real part ([member w]) is always [code]0.0[/code]. </description> </method> <method name="normalized" qualifiers="const"> <return type="Quaternion" /> <description> - Returns a copy of the quaternion, normalized to unit length. + Returns a copy of this quaternion, normalized so that its length is [code]1.0[/code]. See also [method is_normalized]. </description> </method> - <method name="slerp" qualifiers="const"> + <method name="slerp" qualifiers="const" keywords="interpolate"> <return type="Quaternion" /> <param index="0" name="to" type="Quaternion" /> <param index="1" name="weight" type="float" /> <description> - Returns the result of the spherical linear interpolation between this quaternion and [param to] by amount [param weight]. - [b]Note:[/b] Both quaternions must be normalized. + Performs a spherical-linear interpolation with the [param to] quaternion, given a [param weight] and returns the result. Both this quaternion and [param to] must be normalized. </description> </method> <method name="slerpni" qualifiers="const"> @@ -167,7 +181,7 @@ <param index="0" name="to" type="Quaternion" /> <param index="1" name="weight" type="float" /> <description> - Returns the result of the spherical linear interpolation between this quaternion and [param to] by amount [param weight], but without checking if the rotation path is not bigger than 90 degrees. + Performs a spherical-linear interpolation with the [param to] quaternion, given a [param weight] and returns the result. Unlike [method slerp], this method does not check if the rotation path is smaller than 90 degrees. Both this quaternion and [param to] must be normalized. </description> </method> <method name="spherical_cubic_interpolate" qualifiers="const"> @@ -197,25 +211,26 @@ </methods> <members> <member name="w" type="float" setter="" getter="" default="1.0"> - W component of the quaternion (real part). - Quaternion components should usually not be manipulated directly. + W component of the quaternion. This is the "real" part. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. </member> <member name="x" type="float" setter="" getter="" default="0.0"> - X component of the quaternion (imaginary [code]i[/code] axis part). - Quaternion components should usually not be manipulated directly. + X component of the quaternion. This is the value along the "imaginary" [code]i[/code] axis. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. </member> <member name="y" type="float" setter="" getter="" default="0.0"> - Y component of the quaternion (imaginary [code]j[/code] axis part). - Quaternion components should usually not be manipulated directly. + Y component of the quaternion. This is the value along the "imaginary" [code]j[/code] axis. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. </member> <member name="z" type="float" setter="" getter="" default="0.0"> - Z component of the quaternion (imaginary [code]k[/code] axis part). - Quaternion components should usually not be manipulated directly. + Z component of the quaternion. This is the value along the "imaginary" [code]k[/code] axis. + [b]Note:[/b] Quaternion components should usually not be manipulated directly. </member> </members> <constants> <constant name="IDENTITY" value="Quaternion(0, 0, 0, 1)"> - The identity quaternion, representing no rotation. Equivalent to an identity [Basis] matrix. If a vector is transformed by an identity quaternion, it will not change. + The identity quaternion, representing no rotation. This has the same rotation as [constant Basis.IDENTITY]. + If a [Vector3] is rotated (multiplied) by this quaternion, it does not change. </constant> </constants> <operators> @@ -223,7 +238,7 @@ <return type="bool" /> <param index="0" name="right" type="Quaternion" /> <description> - Returns [code]true[/code] if the quaternions are not equal. + Returns [code]true[/code] if the components of both quaternions are not exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -231,63 +246,69 @@ <return type="Quaternion" /> <param index="0" name="right" type="Quaternion" /> <description> - Composes these two quaternions by multiplying them together. This has the effect of rotating the second quaternion (the child) by the first quaternion (the parent). + Composes (multiplies) two quaternions. This rotates the [param right] quaternion (the child) by this quaternion (the parent). </description> </operator> <operator name="operator *"> <return type="Vector3" /> <param index="0" name="right" type="Vector3" /> <description> - Rotates (multiplies) the [Vector3] by the given [Quaternion]. + Rotates (multiplies) the [param right] vector by this quaternion, returning a [Vector3]. </description> </operator> <operator name="operator *"> <return type="Quaternion" /> <param index="0" name="right" type="float" /> <description> - Multiplies each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Multiplies each component of the [Quaternion] by the right [float] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. </description> </operator> <operator name="operator *"> <return type="Quaternion" /> <param index="0" name="right" type="int" /> <description> - Multiplies each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Multiplies each component of the [Quaternion] by the right [int] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. </description> </operator> <operator name="operator +"> <return type="Quaternion" /> <param index="0" name="right" type="Quaternion" /> <description> - Adds each component of the left [Quaternion] to the right [Quaternion]. This operation is not meaningful on its own, but it can be used as a part of a larger expression, such as approximating an intermediate rotation between two nearby rotations. + Adds each component of the left [Quaternion] to the right [Quaternion]. + This operation is not meaningful on its own, but it can be used as a part of a larger expression, such as approximating an intermediate rotation between two nearby rotations. </description> </operator> <operator name="operator -"> <return type="Quaternion" /> <param index="0" name="right" type="Quaternion" /> <description> - Subtracts each component of the left [Quaternion] by the right [Quaternion]. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Subtracts each component of the left [Quaternion] by the right [Quaternion]. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. </description> </operator> <operator name="operator /"> <return type="Quaternion" /> <param index="0" name="right" type="float" /> <description> - Divides each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Divides each component of the [Quaternion] by the right [float] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. </description> </operator> <operator name="operator /"> <return type="Quaternion" /> <param index="0" name="right" type="int" /> <description> - Divides each component of the [Quaternion] by the given value. This operation is not meaningful on its own, but it can be used as a part of a larger expression. + Divides each component of the [Quaternion] by the right [int] value. + This operation is not meaningful on its own, but it can be used as a part of a larger expression. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="Quaternion" /> <description> - Returns [code]true[/code] if the quaternions are exactly equal. + Returns [code]true[/code] if the components of both quaternions are exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -295,7 +316,8 @@ <return type="float" /> <param index="0" name="index" type="int" /> <description> - Access quaternion components using their index. [code]q[0][/code] is equivalent to [code]q.x[/code], [code]q[1][/code] is equivalent to [code]q.y[/code], [code]q[2][/code] is equivalent to [code]q.z[/code], and [code]q[3][/code] is equivalent to [code]q.w[/code]. + Accesses each component of this quaternion by their index. + Index [code]0[/code] is the same as [member x], index [code]1[/code] is the same as [member y], index [code]2[/code] is the same as [member z], and index [code]3[/code] is the same as [member w]. </description> </operator> <operator name="operator unary+"> @@ -307,7 +329,7 @@ <operator name="operator unary-"> <return type="Quaternion" /> <description> - Returns the negative value of the [Quaternion]. This is the same as writing [code]Quaternion(-q.x, -q.y, -q.z, -q.w)[/code]. This operation results in a quaternion that represents the same rotation. + Returns the negative value of the [Quaternion]. This is the same as multiplying all components by [code]-1[/code]. This operation results in a quaternion that represents the same rotation. </description> </operator> </operators> diff --git a/doc/classes/RDPipelineDepthStencilState.xml b/doc/classes/RDPipelineDepthStencilState.xml index fa2a4e17c9..b8245f97af 100644 --- a/doc/classes/RDPipelineDepthStencilState.xml +++ b/doc/classes/RDPipelineDepthStencilState.xml @@ -10,47 +10,67 @@ </tutorials> <members> <member name="back_op_compare" type="int" setter="set_back_op_compare" getter="get_back_op_compare" enum="RenderingDevice.CompareOperator" default="7"> + The method used for comparing the previous back stencil value and [member back_op_reference]. </member> <member name="back_op_compare_mask" type="int" setter="set_back_op_compare_mask" getter="get_back_op_compare_mask" default="0"> + Selects which bits from the back stencil value will be compared. </member> <member name="back_op_depth_fail" type="int" setter="set_back_op_depth_fail" getter="get_back_op_depth_fail" enum="RenderingDevice.StencilOperation" default="1"> + The operation to perform on the stencil buffer for back pixels that pass the stencil test but fail the depth test. </member> <member name="back_op_fail" type="int" setter="set_back_op_fail" getter="get_back_op_fail" enum="RenderingDevice.StencilOperation" default="1"> + The operation to perform on the stencil buffer for back pixels that fail the stencil test </member> <member name="back_op_pass" type="int" setter="set_back_op_pass" getter="get_back_op_pass" enum="RenderingDevice.StencilOperation" default="1"> + The operation to perform on the stencil buffer for back pixels that pass the stencil test. </member> <member name="back_op_reference" type="int" setter="set_back_op_reference" getter="get_back_op_reference" default="0"> + The value the previous back stencil value will be compared to. </member> <member name="back_op_write_mask" type="int" setter="set_back_op_write_mask" getter="get_back_op_write_mask" default="0"> + Selects which bits from the back stencil value will be changed. </member> <member name="depth_compare_operator" type="int" setter="set_depth_compare_operator" getter="get_depth_compare_operator" enum="RenderingDevice.CompareOperator" default="7"> + The method used for comparing the previous and current depth values. </member> <member name="depth_range_max" type="float" setter="set_depth_range_max" getter="get_depth_range_max" default="0.0"> + The maximum depth that returns true for [member enable_depth_range]. </member> <member name="depth_range_min" type="float" setter="set_depth_range_min" getter="get_depth_range_min" default="0.0"> + The minimum depth that returns true for [member enable_depth_range]. </member> <member name="enable_depth_range" type="bool" setter="set_enable_depth_range" getter="get_enable_depth_range" default="false"> + If [code]true[/code], each depth value will be tested to see if it is between [member depth_range_min] and [member depth_range_max]. If it is outside of these values, it is discarded. </member> <member name="enable_depth_test" type="bool" setter="set_enable_depth_test" getter="get_enable_depth_test" default="false"> If [code]true[/code], enables depth testing which allows objects to be automatically occluded by other objects based on their depth. This also allows objects to be partially occluded by other objects. If [code]false[/code], objects will appear in the order they were drawn (like in Godot's 2D renderer). </member> <member name="enable_depth_write" type="bool" setter="set_enable_depth_write" getter="get_enable_depth_write" default="false"> + If [code]true[/code], writes to the depth buffer whenever the depth test returns true. Only works when enable_depth_test is also true. </member> <member name="enable_stencil" type="bool" setter="set_enable_stencil" getter="get_enable_stencil" default="false"> + If [code]true[/code], enables stencil testing. There are separate stencil buffers for front-facing triangles and back-facing triangles. See properties that begin with "front_op" and properties with "back_op" for each. </member> <member name="front_op_compare" type="int" setter="set_front_op_compare" getter="get_front_op_compare" enum="RenderingDevice.CompareOperator" default="7"> + The method used for comparing the previous front stencil value and [member front_op_reference]. </member> <member name="front_op_compare_mask" type="int" setter="set_front_op_compare_mask" getter="get_front_op_compare_mask" default="0"> + Selects which bits from the front stencil value will be compared. </member> <member name="front_op_depth_fail" type="int" setter="set_front_op_depth_fail" getter="get_front_op_depth_fail" enum="RenderingDevice.StencilOperation" default="1"> + The operation to perform on the stencil buffer for front pixels that pass the stencil test but fail the depth test. </member> <member name="front_op_fail" type="int" setter="set_front_op_fail" getter="get_front_op_fail" enum="RenderingDevice.StencilOperation" default="1"> + The operation to perform on the stencil buffer for front pixels that fail the stencil test. </member> <member name="front_op_pass" type="int" setter="set_front_op_pass" getter="get_front_op_pass" enum="RenderingDevice.StencilOperation" default="1"> + The operation to perform on the stencil buffer for front pixels that pass the stencil test. </member> <member name="front_op_reference" type="int" setter="set_front_op_reference" getter="get_front_op_reference" default="0"> + The value the previous front stencil value will be compared to. </member> <member name="front_op_write_mask" type="int" setter="set_front_op_write_mask" getter="get_front_op_write_mask" default="0"> + Selects which bits from the front stencil value will be changed. </member> </members> </class> diff --git a/doc/classes/RDPipelineRasterizationState.xml b/doc/classes/RDPipelineRasterizationState.xml index e97113cce4..034abc688c 100644 --- a/doc/classes/RDPipelineRasterizationState.xml +++ b/doc/classes/RDPipelineRasterizationState.xml @@ -13,17 +13,22 @@ The cull mode to use when drawing polygons, which determines whether front faces or backfaces are hidden. </member> <member name="depth_bias_clamp" type="float" setter="set_depth_bias_clamp" getter="get_depth_bias_clamp" default="0.0"> + A limit for how much each depth value can be offset. If negative, it serves as a minimum value, but if positive, it serves as a maximum value. </member> <member name="depth_bias_constant_factor" type="float" setter="set_depth_bias_constant_factor" getter="get_depth_bias_constant_factor" default="0.0"> + A constant offset added to each depth value. Applied after [member depth_bias_slope_factor]. </member> <member name="depth_bias_enabled" type="bool" setter="set_depth_bias_enabled" getter="get_depth_bias_enabled" default="false"> + If [code]true[/code], each generated depth value will by offset by some amount. The specific amount is generated per polygon based on the values of [member depth_bias_slope_factor] and [member depth_bias_constant_factor]. </member> <member name="depth_bias_slope_factor" type="float" setter="set_depth_bias_slope_factor" getter="get_depth_bias_slope_factor" default="0.0"> + A constant scale applied to the slope of each polygons' depth. Applied before [member depth_bias_constant_factor]. </member> <member name="discard_primitives" type="bool" setter="set_discard_primitives" getter="get_discard_primitives" default="false"> If [code]true[/code], primitives are discarded immediately before the rasterization stage. </member> <member name="enable_depth_clamp" type="bool" setter="set_enable_depth_clamp" getter="get_enable_depth_clamp" default="false"> + If [code]true[/code], clamps depth values according to the minimum and maximum depth of the associated viewport. </member> <member name="front_face" type="int" setter="set_front_face" getter="get_front_face" enum="RenderingDevice.PolygonFrontFace" default="0"> The winding order to use to determine which face of a triangle is considered its front face. diff --git a/doc/classes/RDSamplerState.xml b/doc/classes/RDSamplerState.xml index 44f040dabd..f1ba630226 100644 --- a/doc/classes/RDSamplerState.xml +++ b/doc/classes/RDSamplerState.xml @@ -26,12 +26,13 @@ The mipmap LOD bias to use. Positive values will make the sampler blurrier at a given distance, while negative values will make the sampler sharper at a given distance (at the risk of looking grainy). Recommended values are between [code]-0.5[/code] and [code]0.0[/code]. Only effective if the sampler has mipmaps available. </member> <member name="mag_filter" type="int" setter="set_mag_filter" getter="get_mag_filter" enum="RenderingDevice.SamplerFilter" default="0"> - The sampler's magnification filter. + The sampler's magnification filter. It is the filtering method used when sampling texels that appear bigger than on-screen pixels. </member> <member name="max_lod" type="float" setter="set_max_lod" getter="get_max_lod" default="1e+20"> The maximum mipmap LOD bias to display (lowest resolution). Only effective if the sampler has mipmaps available. </member> <member name="min_filter" type="int" setter="set_min_filter" getter="get_min_filter" enum="RenderingDevice.SamplerFilter" default="0"> + The sampler's minification filter. It is the filtering method used when sampling texels that appear smaller than on-screen pixels. </member> <member name="min_lod" type="float" setter="set_min_lod" getter="get_min_lod" default="0.0"> The minimum mipmap LOD bias to display (highest resolution). Only effective if the sampler has mipmaps available. @@ -49,6 +50,7 @@ The repeat mode to use along the W axis of UV coordinates. This affects the returned values if sampling outside the UV bounds. Only effective for 3D samplers. </member> <member name="unnormalized_uvw" type="bool" setter="set_unnormalized_uvw" getter="get_unnormalized_uvw" default="false"> + If [code]true[/code], the texture will be sampled with coordinates ranging from 0 to the texture's resolution. Otherwise, the coordinates will be normalized and range from 0 to 1. </member> <member name="use_anisotropy" type="bool" setter="set_use_anisotropy" getter="get_use_anisotropy" default="false"> If [code]true[/code], perform anisotropic sampling. See [member anisotropy_max]. diff --git a/doc/classes/RDUniform.xml b/doc/classes/RDUniform.xml index 7aab8b2810..77aaf0aae7 100644 --- a/doc/classes/RDUniform.xml +++ b/doc/classes/RDUniform.xml @@ -13,16 +13,19 @@ <return type="void" /> <param index="0" name="id" type="RID" /> <description> + Binds the given id to the uniform. The data associated with the id is then used when the uniform is passed to a shader. </description> </method> <method name="clear_ids"> <return type="void" /> <description> + Unbinds all ids currently bound to the uniform. </description> </method> <method name="get_ids" qualifiers="const"> <return type="RID[]" /> <description> + Returns an array of all ids currently bound to the uniform. </description> </method> </methods> diff --git a/doc/classes/RandomNumberGenerator.xml b/doc/classes/RandomNumberGenerator.xml index 54f18a1ab4..44e29d2322 100644 --- a/doc/classes/RandomNumberGenerator.xml +++ b/doc/classes/RandomNumberGenerator.xml @@ -6,7 +6,7 @@ <description> RandomNumberGenerator is a class for generating pseudo-random numbers. It currently uses [url=https://www.pcg-random.org/]PCG32[/url]. [b]Note:[/b] The underlying algorithm is an implementation detail and should not be depended upon. - To generate a random float number (within a given range) based on a time-dependant seed: + To generate a random float number (within a given range) based on a time-dependent seed: [codeblock] var rng = RandomNumberGenerator.new() func _ready(): @@ -17,6 +17,25 @@ <link title="Random number generation">$DOCS_URL/tutorials/math/random_number_generation.html</link> </tutorials> <methods> + <method name="rand_weighted"> + <return type="int" /> + <param index="0" name="weights" type="PackedFloat32Array" /> + <description> + Returns a random index with non-uniform weights. Prints an error and returns [code]-1[/code] if the array is empty. + [codeblocks] + [gdscript] + var rng = RandomNumberGenerator.new() + + var my_array = ["one", "two", "three", "four"] + var weights = PackedFloat32Array([0.5, 1, 1, 2]) + + # Prints one of the four elements in `my_array`. + # It is more likely to print "four", and less likely to print "one". + print(my_array[rng.rand_weighted(weights)]) + [/gdscript] + [/codeblocks] + </description> + </method> <method name="randf"> <return type="float" /> <description> @@ -36,7 +55,8 @@ <param index="0" name="mean" type="float" default="0.0" /> <param index="1" name="deviation" type="float" default="1.0" /> <description> - Returns a [url=https://en.wikipedia.org/wiki/Normal_distribution]normally-distributed[/url] pseudo-random number, using Box-Muller transform with the specified [param mean] and a standard [param deviation]. This is also called Gaussian distribution. + Returns a [url=https://en.wikipedia.org/wiki/Normal_distribution]normally-distributed[/url], pseudo-random floating-point number from the specified [param mean] and a standard [param deviation]. This is also known as a Gaussian distribution. + [b]Note:[/b] This method uses the [url=https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform]Box-Muller transform[/url] algorithm. </description> </method> <method name="randi"> diff --git a/doc/classes/RayCast2D.xml b/doc/classes/RayCast2D.xml index 6144fd8f0b..31daaab417 100644 --- a/doc/classes/RayCast2D.xml +++ b/doc/classes/RayCast2D.xml @@ -4,7 +4,7 @@ A ray in 2D space, used to find the first [CollisionObject2D] it intersects. </brief_description> <description> - A raycast represents a ray from its origin to its [member target_position] that finds the closest [CollisionObject2D] along its path, if it intersects any. This is useful for a lot of things, such as + A raycast represents a ray from its origin to its [member target_position] that finds the closest [CollisionObject2D] along its path, if it intersects any. [RayCast2D] can ignore some objects by adding them to an exception list, by making its detection reporting ignore [Area2D]s ([member collide_with_areas]) or [PhysicsBody2D]s ([member collide_with_bodies]), or by configuring physics layers. [RayCast2D] calculates intersection every physics frame, and it holds the result until the next physics frame. For an immediate raycast, or if you want to configure a [RayCast2D] multiple times within the same physics frame, use [method force_raycast_update]. To sweep over a region of 2D space, you can approximate the region with multiple [RayCast2D]s or use [ShapeCast2D]. @@ -69,13 +69,14 @@ <return type="Vector2" /> <description> Returns the normal of the intersecting object's shape at the collision point, or [code]Vector2(0, 0)[/code] if the ray starts inside the shape and [member hit_from_inside] is [code]true[/code]. + [b]Note:[/b] Check that [method is_colliding] returns [code]true[/code] before calling this method to ensure the returned normal is valid and up-to-date. </description> </method> <method name="get_collision_point" qualifiers="const"> <return type="Vector2" /> <description> - Returns the collision point at which the ray intersects the closest object. - [b]Note:[/b] This point is in the [b]global[/b] coordinate system. + Returns the collision point at which the ray intersects the closest object, in the global coordinate system. If [member hit_from_inside] is [code]true[/code] and the ray starts inside of a collision shape, this function will return the origin point of the ray. + [b]Note:[/b] Check that [method is_colliding] returns [code]true[/code] before calling this method to ensure the returned point is valid and up-to-date. </description> </method> <method name="is_colliding" qualifiers="const"> diff --git a/doc/classes/RayCast3D.xml b/doc/classes/RayCast3D.xml index 7157ec9b5f..f9f94e5cfc 100644 --- a/doc/classes/RayCast3D.xml +++ b/doc/classes/RayCast3D.xml @@ -4,7 +4,7 @@ A ray in 3D space, used to find the first [CollisionObject3D] it intersects. </brief_description> <description> - A raycast represents a ray from its origin to its [member target_position] that finds the closest [CollisionObject3D] along its path, if it intersects any. This is useful for a lot of things, such as + A raycast represents a ray from its origin to its [member target_position] that finds the closest [CollisionObject3D] along its path, if it intersects any. [RayCast3D] can ignore some objects by adding them to an exception list, by making its detection reporting ignore [Area3D]s ([member collide_with_areas]) or [PhysicsBody3D]s ([member collide_with_bodies]), or by configuring physics layers. [RayCast3D] calculates intersection every physics frame, and it holds the result until the next physics frame. For an immediate raycast, or if you want to configure a [RayCast3D] multiple times within the same physics frame, use [method force_raycast_update]. To sweep over a region of 3D space, you can approximate the region with multiple [RayCast3D]s or use [ShapeCast3D]. @@ -76,13 +76,14 @@ <return type="Vector3" /> <description> Returns the normal of the intersecting object's shape at the collision point, or [code]Vector3(0, 0, 0)[/code] if the ray starts inside the shape and [member hit_from_inside] is [code]true[/code]. + [b]Note:[/b] Check that [method is_colliding] returns [code]true[/code] before calling this method to ensure the returned normal is valid and up-to-date. </description> </method> <method name="get_collision_point" qualifiers="const"> <return type="Vector3" /> <description> - Returns the collision point at which the ray intersects the closest object. - [b]Note:[/b] This point is in the [b]global[/b] coordinate system. + Returns the collision point at which the ray intersects the closest object, in the global coordinate system. If [member hit_from_inside] is [code]true[/code] and the ray starts inside of a collision shape, this function will return the origin point of the ray. + [b]Note:[/b] Check that [method is_colliding] returns [code]true[/code] before calling this method to ensure the returned point is valid and up-to-date. </description> </method> <method name="is_colliding" qualifiers="const"> diff --git a/doc/classes/RefCounted.xml b/doc/classes/RefCounted.xml index 3ef87e462d..6811170ab0 100644 --- a/doc/classes/RefCounted.xml +++ b/doc/classes/RefCounted.xml @@ -8,7 +8,7 @@ Unlike other [Object] types, [RefCounted]s keep an internal reference counter so that they are automatically released when no longer in use, and only then. [RefCounted]s therefore do not need to be freed manually with [method Object.free]. [RefCounted] instances caught in a cyclic reference will [b]not[/b] be freed automatically. For example, if a node holds a reference to instance [code]A[/code], which directly or indirectly holds a reference back to [code]A[/code], [code]A[/code]'s reference count will be 2. Destruction of the node will leave [code]A[/code] dangling with a reference count of 1, and there will be a memory leak. To prevent this, one of the references in the cycle can be made weak with [method @GlobalScope.weakref]. In the vast majority of use cases, instantiating and using [RefCounted]-derived types is all you need to do. The methods provided in this class are only for advanced users, and can cause issues if misused. - [b]Note:[/b] In C#, reference-counted objects will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free reference-counted objects that are no longer in use. This means that unused ones will linger on for a while before being removed. + [b]Note:[/b] In C#, reference-counted objects will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free reference-counted objects that are no longer in use. This means that unused ones will remain in memory for a while before being removed. </description> <tutorials> <link title="When and how to avoid using nodes for everything">$DOCS_URL/tutorials/best_practices/node_alternatives.html</link> diff --git a/doc/classes/ReflectionProbe.xml b/doc/classes/ReflectionProbe.xml index f53ddfc3ac..367942682e 100644 --- a/doc/classes/ReflectionProbe.xml +++ b/doc/classes/ReflectionProbe.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="ReflectionProbe" inherits="VisualInstance3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="ReflectionProbe" inherits="VisualInstance3D" keywords="environment, envmap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Captures its surroundings to create fast, accurate reflections from a given point. </brief_description> @@ -28,7 +28,8 @@ [b]Note:[/b] To better fit rectangle-shaped rooms that are not aligned to the grid, you can rotate the [ReflectionProbe] node. </member> <member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="1048575"> - Sets the cull mask which determines what objects are drawn by this probe. Every [VisualInstance3D] with a layer included in this cull mask will be rendered by the probe. To improve performance, it is best to only include large objects which are likely to take up a lot of space in the reflection. + Sets the cull mask which determines what objects are drawn by this probe. Every [VisualInstance3D] with a layer included in this cull mask will be rendered by the probe. It is best to only include large objects which are likely to take up a lot of space in the reflection in order to save on rendering cost. + This can also be used to prevent an object from reflecting upon itself (for instance, a [ReflectionProbe] centered on a vehicle). </member> <member name="enable_shadows" type="bool" setter="set_enable_shadows" getter="are_shadows_enabled" default="false"> If [code]true[/code], computes shadows in the reflection probe. This makes the reflection probe slower to render; you may want to disable this if using the [constant UPDATE_ALWAYS] [member update_mode]. @@ -50,6 +51,9 @@ <member name="origin_offset" type="Vector3" setter="set_origin_offset" getter="get_origin_offset" default="Vector3(0, 0, 0)"> Sets the origin offset to be used when this [ReflectionProbe] is in [member box_projection] mode. This can be set to a non-zero value to ensure a reflection fits a rectangle-shaped room, while reducing the number of objects that "get in the way" of the reflection. </member> + <member name="reflection_mask" type="int" setter="set_reflection_mask" getter="get_reflection_mask" default="1048575"> + Sets the reflection mask which determines what objects have reflections applied from this probe. Every [VisualInstance3D] with a layer included in this reflection mask will have reflections applied from this probe. See also [member cull_mask], which can be used to exclude objects from appearing in the reflection while still making them affected by the [ReflectionProbe]. + </member> <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(20, 20, 20)"> The size of the reflection probe. The larger the size, the more space covered by the probe, which will lower the perceived resolution. It is best to keep the size only as large as you need it. [b]Note:[/b] To better fit areas that are not aligned to the grid, you can rotate the [ReflectionProbe] node. diff --git a/doc/classes/RenderData.xml b/doc/classes/RenderData.xml new file mode 100644 index 0000000000..065505e6c6 --- /dev/null +++ b/doc/classes/RenderData.xml @@ -0,0 +1,38 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="RenderData" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Abstract render data object, holds frame data related to rendering a single frame of a viewport. + </brief_description> + <description> + Abstract render data object, exists for the duration of rendering a single viewport. + [b]Note:[/b] This is an internal rendering server object, do not instantiate this from script. + </description> + <tutorials> + </tutorials> + <methods> + <method name="get_camera_attributes" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of the camera attributes object in the [RenderingServer] being used to render this viewport. + </description> + </method> + <method name="get_environment" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of the environments object in the [RenderingServer] being used to render this viewport. + </description> + </method> + <method name="get_render_scene_buffers" qualifiers="const"> + <return type="RenderSceneBuffers" /> + <description> + Returns the [RenderSceneBuffers] object managing the scene buffers for rendering this viewport. + </description> + </method> + <method name="get_render_scene_data" qualifiers="const"> + <return type="RenderSceneData" /> + <description> + Returns the [RenderSceneData] object managing this frames scene data. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/RenderDataExtension.xml b/doc/classes/RenderDataExtension.xml new file mode 100644 index 0000000000..9bdab8e101 --- /dev/null +++ b/doc/classes/RenderDataExtension.xml @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="RenderDataExtension" inherits="RenderData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + This class allows for a RenderData implementation to be made in GDExtension. + </brief_description> + <description> + This class allows for a RenderData implementation to be made in GDExtension. + </description> + <tutorials> + </tutorials> + <methods> + <method name="_get_camera_attributes" qualifiers="virtual const"> + <return type="RID" /> + <description> + Implement this in GDExtension to return the [RID] for the implementations camera attributes object. + </description> + </method> + <method name="_get_environment" qualifiers="virtual const"> + <return type="RID" /> + <description> + </description> + </method> + <method name="_get_render_scene_buffers" qualifiers="virtual const"> + <return type="RenderSceneBuffers" /> + <description> + Implement this in GDExtension to return the [RID] of the implementations environment object. + </description> + </method> + <method name="_get_render_scene_data" qualifiers="virtual const"> + <return type="RenderSceneData" /> + <description> + Implement this in GDExtension to return the implementations [RenderSceneDataExtension] object. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/RenderDataRD.xml b/doc/classes/RenderDataRD.xml new file mode 100644 index 0000000000..eb32c29648 --- /dev/null +++ b/doc/classes/RenderDataRD.xml @@ -0,0 +1,13 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="RenderDataRD" inherits="RenderData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Render data implementation for the RenderingDevice based renderers. + [b]Note:[/b] This is an internal rendering server object, do not instantiate this from script. + </brief_description> + <description> + This object manages all render data for the rendering device based renderers. + [b]Note:[/b] This is an internal rendering server object only exposed for GDExtension plugins. + </description> + <tutorials> + </tutorials> +</class> diff --git a/doc/classes/RenderSceneBuffers.xml b/doc/classes/RenderSceneBuffers.xml index b2a5213dba..1a1c3f413b 100644 --- a/doc/classes/RenderSceneBuffers.xml +++ b/doc/classes/RenderSceneBuffers.xml @@ -5,7 +5,7 @@ </brief_description> <description> Abstract scene buffers object, created for each viewport for which 3D rendering is done. It manages any additional buffers used during rendering and will discard buffers when the viewport is resized. - [b]Note:[/b] this is an internal rendering server object only exposed for GDExtension plugins. + [b]Note:[/b] This is an internal rendering server object, do not instantiate this from script. </description> <tutorials> </tutorials> diff --git a/doc/classes/RenderSceneBuffersRD.xml b/doc/classes/RenderSceneBuffersRD.xml index 6ab1e6bbbd..359f0b33a8 100644 --- a/doc/classes/RenderSceneBuffersRD.xml +++ b/doc/classes/RenderSceneBuffersRD.xml @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="RenderSceneBuffersRD" inherits="RenderSceneBuffers" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Abstract render scene buffer implementation for the RenderingDevice based renderers. + Render scene buffer implementation for the RenderingDevice based renderers. </brief_description> <description> This object manages all 3D rendering buffers for the rendering device based renderers. An instance of this object is created for every viewport that has 3D rendering enabled. All buffers are organized in [b]contexts[/b]. The default context is called [b]render_buffers[/b] and can contain amongst others the color buffer, depth buffer, velocity buffers, VRS density map and MSAA variants of these buffers. Buffers are only guaranteed to exist during rendering of the viewport. - [b]Note:[/b] this is an internal rendering server object only exposed for GDExtension plugins. + [b]Note:[/b] This is an internal rendering server object, do not instantiate this from script. </description> <tutorials> </tutorials> @@ -58,27 +58,35 @@ <method name="get_color_layer"> <return type="RID" /> <param index="0" name="layer" type="int" /> + <param index="1" name="msaa" type="bool" default="false" /> <description> Returns the specified layer from the color texture we are rendering 3D content to. + If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_color_texture"> <return type="RID" /> + <param index="0" name="msaa" type="bool" default="false" /> <description> Returns the color texture we are rendering 3D content to. If multiview is used this will be a texture array with all views. + If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_depth_layer"> <return type="RID" /> <param index="0" name="layer" type="int" /> + <param index="1" name="msaa" type="bool" default="false" /> <description> Returns the specified layer from the depth texture we are rendering 3D content to. + If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_depth_texture"> <return type="RID" /> + <param index="0" name="msaa" type="bool" default="false" /> <description> Returns the depth texture we are rendering 3D content to. If multiview is used this will be a texture array with all views. + If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_internal_size" qualifiers="const"> @@ -87,6 +95,12 @@ Returns the internal size of the render buffer (size before upscaling) with which textures are created by default. </description> </method> + <method name="get_msaa_3d" qualifiers="const"> + <return type="int" enum="RenderingServer.ViewportMSAA" /> + <description> + Returns the applied 3D MSAA mode for this viewport. + </description> + </method> <method name="get_render_target" qualifiers="const"> <return type="RID" /> <description> @@ -152,14 +166,17 @@ <method name="get_velocity_layer"> <return type="RID" /> <param index="0" name="layer" type="int" /> + <param index="1" name="msaa" type="bool" default="false" /> <description> Returns the specified layer from the velocity texture we are rendering 3D content to. </description> </method> <method name="get_velocity_texture"> <return type="RID" /> + <param index="0" name="msaa" type="bool" default="false" /> <description> Returns the velocity texture we are rendering 3D content to. If multiview is used this will be a texture array with all views. + If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_view_count" qualifiers="const"> diff --git a/doc/classes/RenderSceneData.xml b/doc/classes/RenderSceneData.xml new file mode 100644 index 0000000000..0ac13ca6d8 --- /dev/null +++ b/doc/classes/RenderSceneData.xml @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="RenderSceneData" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Abstract render data object, holds scene data related to rendering a single frame of a viewport. + </brief_description> + <description> + Abstract scene data object, exists for the duration of rendering a single viewport. + [b]Note:[/b] This is an internal rendering server object, do not instantiate this from script. + </description> + <tutorials> + </tutorials> + <methods> + <method name="get_cam_projection" qualifiers="const"> + <return type="Projection" /> + <description> + Returns the camera projection used to render this frame. + [b]Note:[/b] If more than one view is rendered, this will return a combined projection. + </description> + </method> + <method name="get_cam_transform" qualifiers="const"> + <return type="Transform3D" /> + <description> + Returns the camera transform used to render this frame. + [b]Note:[/b] If more than one view is rendered, this will return a centered transform. + </description> + </method> + <method name="get_uniform_buffer" qualifiers="const"> + <return type="RID" /> + <description> + Return the [RID] of the uniform buffer containing the scene data as a UBO. + </description> + </method> + <method name="get_view_count" qualifiers="const"> + <return type="int" /> + <description> + Returns the number of views being rendered. + </description> + </method> + <method name="get_view_eye_offset" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="view" type="int" /> + <description> + Returns the eye offset per view used to render this frame. This is the offset between our camera transform and the eye transform. + </description> + </method> + <method name="get_view_projection" qualifiers="const"> + <return type="Projection" /> + <param index="0" name="view" type="int" /> + <description> + Returns the view projection per view used to render this frame. + [b]Note:[/b] If a single view is rendered, this returns the camera projection. If more than one view is rendered, this will return a projection for the given view including the eye offset. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/RenderSceneDataExtension.xml b/doc/classes/RenderSceneDataExtension.xml new file mode 100644 index 0000000000..72eb7fc54d --- /dev/null +++ b/doc/classes/RenderSceneDataExtension.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="RenderSceneDataExtension" inherits="RenderSceneData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + This class allows for a RenderSceneData implementation to be made in GDExtension. + </brief_description> + <description> + This class allows for a RenderSceneData implementation to be made in GDExtension. + </description> + <tutorials> + </tutorials> + <methods> + <method name="_get_cam_projection" qualifiers="virtual const"> + <return type="Projection" /> + <description> + Implement this in GDExtension to return the camera [Projection]. + </description> + </method> + <method name="_get_cam_transform" qualifiers="virtual const"> + <return type="Transform3D" /> + <description> + Implement this in GDExtension to return the camera [Transform3D]. + </description> + </method> + <method name="_get_uniform_buffer" qualifiers="virtual const"> + <return type="RID" /> + <description> + Implement this in GDExtension to return the [RID] of the uniform buffer containing the scene data as a UBO. + </description> + </method> + <method name="_get_view_count" qualifiers="virtual const"> + <return type="int" /> + <description> + Implement this in GDExtension to return the view count. + </description> + </method> + <method name="_get_view_eye_offset" qualifiers="virtual const"> + <return type="Vector3" /> + <param index="0" name="view" type="int" /> + <description> + Implement this in GDExtension to return the eye offset for the given [param view]. + </description> + </method> + <method name="_get_view_projection" qualifiers="virtual const"> + <return type="Projection" /> + <param index="0" name="view" type="int" /> + <description> + Implement this in GDExtension to return the view [Projection] for the given [param view]. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/RenderSceneDataRD.xml b/doc/classes/RenderSceneDataRD.xml new file mode 100644 index 0000000000..d9a382a982 --- /dev/null +++ b/doc/classes/RenderSceneDataRD.xml @@ -0,0 +1,12 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="RenderSceneDataRD" inherits="RenderSceneData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Render scene data implementation for the RenderingDevice based renderers. + </brief_description> + <description> + Object holds scene data related to rendering a single frame of a viewport. + [b]Note:[/b] This is an internal rendering server object, do not instantiate this from script. + </description> + <tutorials> + </tutorials> +</class> diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index 20faa70226..33cd831175 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -14,12 +14,12 @@ <link title="Using compute shaders">$DOCS_URL/tutorials/shaders/compute_shaders.html</link> </tutorials> <methods> - <method name="barrier"> + <method name="barrier" deprecated="Barriers are automatically inserted by RenderingDevice."> <return type="void" /> <param index="0" name="from" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <param index="1" name="to" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> - Puts a memory barrier in place. This is used for synchronization to avoid data races. See also [method full_barrier], which may be useful for debugging. + This method does nothing. </description> </method> <method name="buffer_clear"> @@ -27,9 +27,8 @@ <param index="0" name="buffer" type="RID" /> <param index="1" name="offset" type="int" /> <param index="2" name="size_bytes" type="int" /> - <param index="3" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> - Clears the contents of the [param buffer], clearing [param size_bytes] bytes, starting at [param offset]. Always raises a memory barrier. + Clears the contents of the [param buffer], clearing [param size_bytes] bytes, starting at [param offset]. Prints an error if: - the size isn't a multiple of four - the region specified by [param offset] + [param size_bytes] exceeds the buffer @@ -37,6 +36,21 @@ - a compute list is currently active (created by [method compute_list_begin]) </description> </method> + <method name="buffer_copy"> + <return type="int" enum="Error" /> + <param index="0" name="src_buffer" type="RID" /> + <param index="1" name="dst_buffer" type="RID" /> + <param index="2" name="src_offset" type="int" /> + <param index="3" name="dst_offset" type="int" /> + <param index="4" name="size" type="int" /> + <description> + Copies [param size] bytes from the [param src_buffer] at [param src_offset] into [param dst_buffer] at [param dst_offset]. + Prints an error if: + - [param size] exceeds the size of either [param src_buffer] or [param dst_buffer] at their corresponding offsets + - a draw list is currently active (created by [method draw_list_begin]) + - a compute list is currently active (created by [method compute_list_begin]) + </description> + </method> <method name="buffer_get_data"> <return type="PackedByteArray" /> <param index="0" name="buffer" type="RID" /> @@ -52,9 +66,8 @@ <param index="1" name="offset" type="int" /> <param index="2" name="size_bytes" type="int" /> <param index="3" name="data" type="PackedByteArray" /> - <param index="4" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> - Updates a region of [param size_bytes] bytes, starting at [param offset], in the buffer, with the specified [param data]. Raises a memory barrier except when [param post_barrier] is set to [constant BARRIER_MASK_NO_BARRIER]. + Updates a region of [param size_bytes] bytes, starting at [param offset], in the buffer, with the specified [param data]. Prints an error if: - the region specified by [param offset] + [param size_bytes] exceeds the buffer - a draw list is currently active (created by [method draw_list_begin]) @@ -77,10 +90,9 @@ </method> <method name="compute_list_begin"> <return type="int" /> - <param index="0" name="allow_draw_overlap" type="bool" default="false" /> <description> Starts a list of compute commands created with the [code]compute_*[/code] methods. The returned value should be passed to other [code]compute_list_*[/code] functions. - If [param allow_draw_overlap] is [code]true[/code], you may have one draw list running at the same time as one compute list. Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using [method compute_list_end]. + Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using [method compute_list_end]. A simple compute operation might look like this (code is not a complete example): [codeblock] var rd = RenderingDevice.new() @@ -128,7 +140,6 @@ </method> <method name="compute_list_end"> <return type="void" /> - <param index="0" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Finishes a list of compute commands created with the [code]compute_*[/code] methods. </description> @@ -170,7 +181,7 @@ <param index="1" name="color" type="Color" /> <description> Create a command buffer debug label region that can be displayed in third-party tools such as [url=https://renderdoc.org/]RenderDoc[/url]. All regions must be ended with a [method draw_command_end_label] call. When viewed from the linear series of submissions to a single queue, calls to [method draw_command_begin_label] and [method draw_command_end_label] must be matched and balanced. - The [code]VK_EXT_DEBUG_UTILS_EXTENSION_NAME[/code] Vulkan extension must be available and enabled for command buffer debug label region to work. See also [method draw_command_insert_label] and [method draw_command_end_label]. + The [code]VK_EXT_DEBUG_UTILS_EXTENSION_NAME[/code] Vulkan extension must be available and enabled for command buffer debug label region to work. See also [method draw_command_end_label]. </description> </method> <method name="draw_command_end_label"> @@ -179,12 +190,12 @@ Ends the command buffer debug label region started by a [method draw_command_begin_label] call. </description> </method> - <method name="draw_command_insert_label"> + <method name="draw_command_insert_label" deprecated="Inserting labels no longer applies due to command reordering."> <return type="void" /> <param index="0" name="name" type="String" /> <param index="1" name="color" type="Color" /> <description> - Inserts a command buffer debug label region in the current command buffer. Unlike [method draw_command_begin_label], this region should not be ended with a [method draw_command_end_label] call. + This method does nothing. </description> </method> <method name="draw_list_begin"> @@ -198,14 +209,13 @@ <param index="6" name="clear_depth" type="float" default="1.0" /> <param index="7" name="clear_stencil" type="int" default="0" /> <param index="8" name="region" type="Rect2" default="Rect2(0, 0, 0, 0)" /> - <param index="9" name="storage_textures" type="RID[]" default="[]" /> <description> Starts a list of raster drawing commands created with the [code]draw_*[/code] methods. The returned value should be passed to other [code]draw_list_*[/code] functions. Multiple draw lists cannot be created at the same time; you must finish the previous draw list first using [method draw_list_end]. A simple drawing operation might look like this (code is not a complete example): [codeblock] var rd = RenderingDevice.new() - var clear_colors = PackedColorArray([Color(0, 0, 0, 0), Color(0, 0, 0, 0), Color(0, 0, 0, 0)] + var clear_colors = PackedColorArray([Color(0, 0, 0, 0), Color(0, 0, 0, 0), Color(0, 0, 0, 0)]) var draw_list = rd.draw_list_begin(framebuffers[i], RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_READ, RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_DISCARD, clear_colors) # Draw opaque. @@ -232,7 +242,7 @@ [b]Note:[/b] Cannot be used with local RenderingDevices, as these don't have a screen. If called on a local RenderingDevice, [method draw_list_begin_for_screen] returns [constant INVALID_ID]. </description> </method> - <method name="draw_list_begin_split"> + <method name="draw_list_begin_split" deprecated="Split draw lists are used automatically by RenderingDevice."> <return type="PackedInt64Array" /> <param index="0" name="framebuffer" type="RID" /> <param index="1" name="splits" type="int" /> @@ -246,7 +256,7 @@ <param index="9" name="region" type="Rect2" default="Rect2(0, 0, 0, 0)" /> <param index="10" name="storage_textures" type="RID[]" default="[]" /> <description> - Variant of [method draw_list_begin] with support for multiple splits. The [param splits] parameter determines how many splits are created. + This method does nothing and always returns an empty [PackedInt64Array]. </description> </method> <method name="draw_list_bind_index_array"> @@ -310,7 +320,6 @@ </method> <method name="draw_list_end"> <return type="void" /> - <param index="0" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Finishes a list of raster drawing commands created with the [code]draw_*[/code] methods. </description> @@ -335,14 +344,14 @@ <method name="draw_list_switch_to_next_pass"> <return type="int" /> <description> - Switches to the next draw pass and returns the split's ID. Equivalent to [method draw_list_switch_to_next_pass_split] with [code]splits[/code] set to [code]1[/code]. + Switches to the next draw pass. </description> </method> - <method name="draw_list_switch_to_next_pass_split"> + <method name="draw_list_switch_to_next_pass_split" deprecated="Split draw lists are used automatically by RenderingDevice."> <return type="PackedInt64Array" /> <param index="0" name="splits" type="int" /> <description> - Switches to the next draw pass, with the number of splits allocated specified in [param splits]. The return value is an array containing the ID of each split. For single-split usage, see [method draw_list_switch_to_next_pass]. + This method does nothing and always returns an empty [PackedInt64Array]. </description> </method> <method name="framebuffer_create"> @@ -430,10 +439,10 @@ Tries to free an object in the RenderingDevice. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RenderingDevice directly. </description> </method> - <method name="full_barrier"> + <method name="full_barrier" deprecated="Barriers are automatically inserted by RenderingDevice."> <return type="void" /> <description> - Puts a [i]full[/i] memory barrier in place. This is a memory [method barrier] with all flags enabled. [method full_barrier] it should only be used for debugging as it can severely impact performance. + This method does nothing. </description> </method> <method name="get_captured_timestamp_cpu_time" qualifiers="const"> @@ -581,8 +590,9 @@ </method> <method name="screen_get_framebuffer_format" qualifiers="const"> <return type="int" /> + <param index="0" name="screen" type="int" default="0" /> <description> - Returns the screen's framebuffer format. + Returns the framebuffer format of the given screen. [b]Note:[/b] Only the main [RenderingDevice] returned by [method RenderingServer.get_rendering_device] has a format. If called on a local [RenderingDevice], this method prints an error and returns [constant INVALID_ID]. </description> </method> @@ -704,7 +714,6 @@ <param index="3" name="mipmap_count" type="int" /> <param index="4" name="base_layer" type="int" /> <param index="5" name="layer_count" type="int" /> - <param index="6" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Clears the specified [param texture] by replacing all of its pixels with the specified [param color]. [param base_mipmap] and [param mipmap_count] determine which mipmaps of the texture are affected by this clear operation, while [param base_layer] and [param layer_count] determine which layers of a 3D texture (or texture array) are affected by this clear operation. For 2D textures (which only have one layer by design), [param base_layer] must be [code]0[/code] and [param layer_count] must be [code]1[/code]. [b]Note:[/b] [param texture] can't be cleared while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to clear this texture. @@ -721,7 +730,6 @@ <param index="6" name="dst_mipmap" type="int" /> <param index="7" name="src_layer" type="int" /> <param index="8" name="dst_layer" type="int" /> - <param index="9" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Copies the [param from_texture] to [param to_texture] with the specified [param from_pos], [param to_pos] and [param size] coordinates. The Z axis of the [param from_pos], [param to_pos] and [param size] must be [code]0[/code] for 2-dimensional textures. Source and destination mipmaps/layers must also be specified, with these parameters being [code]0[/code] for textures without mipmaps or single-layer textures. Returns [constant @GlobalScope.OK] if the texture copy was successful or [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. [b]Note:[/b] [param from_texture] texture can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to copy this texture. @@ -796,7 +804,7 @@ Returns the data format used to create this texture. </description> </method> - <method name="texture_get_native_handle"> + <method name="texture_get_native_handle" deprecated="Use [method get_driver_resource] with [constant DRIVER_RESOURCE_TEXTURE] instead."> <return type="int" /> <param index="0" name="texture" type="RID" /> <description> @@ -830,7 +838,6 @@ <return type="int" enum="Error" /> <param index="0" name="from_texture" type="RID" /> <param index="1" name="to_texture" type="RID" /> - <param index="2" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Resolves the [param from_texture] texture onto [param to_texture] with multisample antialiasing enabled. This must be used when rendering a framebuffer for MSAA to work. Returns [constant @GlobalScope.OK] if successful, [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. [b]Note:[/b] [param from_texture] and [param to_texture] textures must have the same dimension, format and type (color or depth). @@ -847,7 +854,6 @@ <param index="0" name="texture" type="RID" /> <param index="1" name="layer" type="int" /> <param index="2" name="data" type="PackedByteArray" /> - <param index="3" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Updates texture data with new data, replacing the previous data in place. The updated texture data must have the same dimensions and format. For 2D textures (which only have one layer), [param layer] must be [code]0[/code]. Returns [constant @GlobalScope.OK] if the update was successful, [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. [b]Note:[/b] Updating textures is forbidden during creation of a draw or compute list. @@ -928,44 +934,78 @@ <constant name="DEVICE_TYPE_MAX" value="5" enum="DeviceType"> Represents the size of the [enum DeviceType] enum. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_DEVICE" value="0" enum="DriverResource"> - Vulkan device driver resource. This is a "global" resource and ignores the RID passed in + <constant name="DRIVER_RESOURCE_LOGICAL_DEVICE" value="0" enum="DriverResource"> + Specific device object based on a physical device. + - Vulkan: Vulkan device driver resource ([code]VkDevice[/code]). ([code]rid[/code] argument doesn't apply.) + </constant> + <constant name="DRIVER_RESOURCE_PHYSICAL_DEVICE" value="1" enum="DriverResource"> + Physical device the specific logical device is based on. + - Vulkan: [code]VkDevice[/code]. ([code]rid[/code] argument doesn't apply.) + </constant> + <constant name="DRIVER_RESOURCE_TOPMOST_OBJECT" value="2" enum="DriverResource"> + Top-most graphics API entry object. + - Vulkan: [code]VkInstance[/code]. ([code]rid[/code] argument doesn't apply.) + </constant> + <constant name="DRIVER_RESOURCE_COMMAND_QUEUE" value="3" enum="DriverResource"> + The main graphics-compute command queue. + - Vulkan: [code]VkQueue[/code]. ([code]rid[/code] argument doesn't apply.) + </constant> + <constant name="DRIVER_RESOURCE_QUEUE_FAMILY" value="4" enum="DriverResource"> + The specific family the main queue belongs to. + - Vulkan: the queue family index, an [code]uint32_t[/code]. ([code]rid[/code] argument doesn't apply.) + </constant> + <constant name="DRIVER_RESOURCE_TEXTURE" value="5" enum="DriverResource"> + - Vulkan: [code]VkImage[/code]. + </constant> + <constant name="DRIVER_RESOURCE_TEXTURE_VIEW" value="6" enum="DriverResource"> + The view of an owned or shared texture. + - Vulkan: [code]VkImageView[/code]. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_PHYSICAL_DEVICE" value="1" enum="DriverResource"> - Physical device (graphics card) driver resource. + <constant name="DRIVER_RESOURCE_TEXTURE_DATA_FORMAT" value="7" enum="DriverResource"> + The native id of the data format of the texture. + - Vulkan: [code]VkFormat[/code]. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_INSTANCE" value="2" enum="DriverResource"> - Vulkan instance driver resource. + <constant name="DRIVER_RESOURCE_SAMPLER" value="8" enum="DriverResource"> + - Vulkan: [code]VkSampler[/code]. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_QUEUE" value="3" enum="DriverResource"> - Vulkan queue driver resource. + <constant name="DRIVER_RESOURCE_UNIFORM_SET" value="9" enum="DriverResource"> + - Vulkan: [code]VkDescriptorSet[/code]. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_QUEUE_FAMILY_INDEX" value="4" enum="DriverResource"> - Vulkan queue family index driver resource. + <constant name="DRIVER_RESOURCE_BUFFER" value="10" enum="DriverResource"> + Buffer of any kind of (storage, vertex, etc.). + - Vulkan: [code]VkBuffer[/code]. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_IMAGE" value="5" enum="DriverResource"> - Vulkan image driver resource. + <constant name="DRIVER_RESOURCE_COMPUTE_PIPELINE" value="11" enum="DriverResource"> + - Vulkan: [code]VkPipeline[/code]. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_IMAGE_VIEW" value="6" enum="DriverResource"> - Vulkan image view driver resource. + <constant name="DRIVER_RESOURCE_RENDER_PIPELINE" value="12" enum="DriverResource"> + - Vulkan: [code]VkPipeline[/code]. </constant> - <constant name="DRIVER_RESOURCE_VULKAN_IMAGE_NATIVE_TEXTURE_FORMAT" value="7" enum="DriverResource"> - Vulkan image native texture format driver resource. + <constant name="DRIVER_RESOURCE_VULKAN_DEVICE" value="0" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_LOGICAL_DEVICE] instead."> </constant> - <constant name="DRIVER_RESOURCE_VULKAN_SAMPLER" value="8" enum="DriverResource"> - Vulkan sampler driver resource. + <constant name="DRIVER_RESOURCE_VULKAN_PHYSICAL_DEVICE" value="1" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_PHYSICAL_DEVICE] instead."> </constant> - <constant name="DRIVER_RESOURCE_VULKAN_DESCRIPTOR_SET" value="9" enum="DriverResource"> - Vulkan [url=https://vkguide.dev/docs/chapter-4/descriptors/]descriptor set[/url] driver resource. + <constant name="DRIVER_RESOURCE_VULKAN_INSTANCE" value="2" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_TOPMOST_OBJECT] instead."> </constant> - <constant name="DRIVER_RESOURCE_VULKAN_BUFFER" value="10" enum="DriverResource"> - Vulkan buffer driver resource. + <constant name="DRIVER_RESOURCE_VULKAN_QUEUE" value="3" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_COMMAND_QUEUE] instead."> </constant> - <constant name="DRIVER_RESOURCE_VULKAN_COMPUTE_PIPELINE" value="11" enum="DriverResource"> - Vulkan compute pipeline driver resource. + <constant name="DRIVER_RESOURCE_VULKAN_QUEUE_FAMILY_INDEX" value="4" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_QUEUE_FAMILY] instead."> </constant> - <constant name="DRIVER_RESOURCE_VULKAN_RENDER_PIPELINE" value="12" enum="DriverResource"> - Vulkan render pipeline driver resource. + <constant name="DRIVER_RESOURCE_VULKAN_IMAGE" value="5" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_TEXTURE] instead."> + </constant> + <constant name="DRIVER_RESOURCE_VULKAN_IMAGE_VIEW" value="6" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_TEXTURE_VIEW] instead."> + </constant> + <constant name="DRIVER_RESOURCE_VULKAN_IMAGE_NATIVE_TEXTURE_FORMAT" value="7" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_TEXTURE_DATA_FORMAT] instead."> + </constant> + <constant name="DRIVER_RESOURCE_VULKAN_SAMPLER" value="8" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_SAMPLER] instead."> + </constant> + <constant name="DRIVER_RESOURCE_VULKAN_DESCRIPTOR_SET" value="9" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_UNIFORM_SET] instead."> + </constant> + <constant name="DRIVER_RESOURCE_VULKAN_BUFFER" value="10" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_BUFFER] instead."> + </constant> + <constant name="DRIVER_RESOURCE_VULKAN_COMPUTE_PIPELINE" value="11" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_COMPUTE_PIPELINE] instead."> + </constant> + <constant name="DRIVER_RESOURCE_VULKAN_RENDER_PIPELINE" value="12" enum="DriverResource" deprecated="Use [constant DRIVER_RESOURCE_RENDER_PIPELINE] instead."> </constant> <constant name="DATA_FORMAT_R4G4_UNORM_PACK8" value="0" enum="DataFormat"> 4-bit-per-channel red/green channel data format, packed into 8 bits. Values are in the [code][0.0, 1.0][/code] range. @@ -2102,39 +2142,41 @@ </constant> <constant name="DYNAMIC_STATE_STENCIL_REFERENCE" value="64" enum="PipelineDynamicStateFlags" is_bitfield="true"> </constant> - <constant name="INITIAL_ACTION_CLEAR" value="0" enum="InitialAction"> - Start rendering and clear the whole framebuffer. + <constant name="INITIAL_ACTION_LOAD" value="0" enum="InitialAction"> + Load the previous contents of the framebuffer. </constant> - <constant name="INITIAL_ACTION_CLEAR_REGION" value="1" enum="InitialAction"> - Start rendering and clear the framebuffer in the specified region. + <constant name="INITIAL_ACTION_CLEAR" value="1" enum="InitialAction"> + Clear the whole framebuffer or its specified region. </constant> - <constant name="INITIAL_ACTION_CLEAR_REGION_CONTINUE" value="2" enum="InitialAction"> - Continue rendering and clear the framebuffer in the specified region. Framebuffer must have been left in [constant FINAL_ACTION_CONTINUE] state as the final action previously. + <constant name="INITIAL_ACTION_DISCARD" value="2" enum="InitialAction"> + Ignore the previous contents of the framebuffer. This is the fastest option if you'll overwrite all of the pixels and don't need to read any of them. </constant> - <constant name="INITIAL_ACTION_KEEP" value="3" enum="InitialAction"> - Start rendering, but keep attached color texture contents. If the framebuffer was previously used to read in a shader, this will automatically insert a layout transition. + <constant name="INITIAL_ACTION_MAX" value="3" enum="InitialAction"> + Represents the size of the [enum InitialAction] enum. </constant> - <constant name="INITIAL_ACTION_DROP" value="4" enum="InitialAction"> - Start rendering, ignore what is there; write above it. In general, this is the fastest option when you will be writing every single pixel and you don't need a clear color. + <constant name="INITIAL_ACTION_CLEAR_REGION" value="1" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_CLEAR] instead."> </constant> - <constant name="INITIAL_ACTION_CONTINUE" value="5" enum="InitialAction"> - Continue rendering. Framebuffer must have been left in [constant FINAL_ACTION_CONTINUE] state as the final action previously. + <constant name="INITIAL_ACTION_CLEAR_REGION_CONTINUE" value="1" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_LOAD] instead."> </constant> - <constant name="INITIAL_ACTION_MAX" value="6" enum="InitialAction"> - Represents the size of the [enum InitialAction] enum. + <constant name="INITIAL_ACTION_KEEP" value="0" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_LOAD] instead."> </constant> - <constant name="FINAL_ACTION_READ" value="0" enum="FinalAction"> - Store the texture for reading and make it read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit (only applies to color, depth and stencil attachments). + <constant name="INITIAL_ACTION_DROP" value="2" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_DISCARD] instead."> </constant> - <constant name="FINAL_ACTION_DISCARD" value="1" enum="FinalAction"> - Discard the texture data and make it read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit (only applies to color, depth and stencil attachments). + <constant name="INITIAL_ACTION_CONTINUE" value="0" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_LOAD] instead."> </constant> - <constant name="FINAL_ACTION_CONTINUE" value="2" enum="FinalAction"> - Store the texture and continue for further processing. Similar to [constant FINAL_ACTION_READ], but does not make the texture read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit. + <constant name="FINAL_ACTION_STORE" value="0" enum="FinalAction"> + Store the result of the draw list in the framebuffer. This is generally what you want to do. </constant> - <constant name="FINAL_ACTION_MAX" value="3" enum="FinalAction"> + <constant name="FINAL_ACTION_DISCARD" value="1" enum="FinalAction"> + Discard the contents of the framebuffer. This is the fastest option if you don't need to use the results of the draw list. + </constant> + <constant name="FINAL_ACTION_MAX" value="2" enum="FinalAction"> Represents the size of the [enum FinalAction] enum. </constant> + <constant name="FINAL_ACTION_READ" value="0" enum="FinalAction" deprecated="Use [constant FINAL_ACTION_STORE] instead."> + </constant> + <constant name="FINAL_ACTION_CONTINUE" value="0" enum="FinalAction" deprecated="Use [constant FINAL_ACTION_STORE] instead."> + </constant> <constant name="SHADER_STAGE_VERTEX" value="0" enum="ShaderStage"> Vertex shader stage. This can be used to manipulate vertices from a shader (but not create new vertices). </constant> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index da07582773..c74d61ab88 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -118,6 +118,14 @@ Sets the camera_attributes created with [method camera_attributes_create] to the given camera. </description> </method> + <method name="camera_set_compositor"> + <return type="void" /> + <param index="0" name="camera" type="RID" /> + <param index="1" name="compositor" type="RID" /> + <description> + Sets the compositor used by this camera. Equivalent to [member Camera3D.compositor]. + </description> + </method> <method name="camera_set_cull_mask"> <return type="void" /> <param index="0" name="camera" type="RID" /> @@ -416,6 +424,14 @@ [b]Note:[/b] The equivalent node is [CanvasItem]. </description> </method> + <method name="canvas_item_reset_physics_interpolation"> + <return type="void" /> + <param index="0" name="item" type="RID" /> + <description> + Prevents physics interpolation for the current physics tick. + This is useful when moving a canvas item to a new location, to give an instantaneous change rather than interpolation from the previous location. + </description> + </method> <method name="canvas_item_set_canvas_group_mode"> <return type="void" /> <param index="0" name="item" type="RID" /> @@ -496,6 +512,14 @@ Sets the index for the [CanvasItem]. </description> </method> + <method name="canvas_item_set_interpolated"> + <return type="void" /> + <param index="0" name="item" type="RID" /> + <param index="1" name="interpolated" type="bool" /> + <description> + If [param interpolated] is [code]true[/code], turns on physics interpolation for the canvas item. + </description> + </method> <method name="canvas_item_set_light_mask"> <return type="void" /> <param index="0" name="item" type="RID" /> @@ -604,6 +628,15 @@ Sets the [CanvasItem]'s Z index, i.e. its draw order (lower indexes are drawn first). </description> </method> + <method name="canvas_item_transform_physics_interpolation"> + <return type="void" /> + <param index="0" name="item" type="RID" /> + <param index="1" name="transform" type="Transform2D" /> + <description> + Transforms both the current and previous stored transform for a canvas item. + This allows transforming a canvas item without creating a "glitch" in the interpolation, which is particularly useful for large worlds utilising a shifting origin. + </description> + </method> <method name="canvas_light_attach_to_canvas"> <return type="void" /> <param index="0" name="light" type="RID" /> @@ -636,6 +669,14 @@ [b]Note:[/b] The equivalent node is [LightOccluder2D]. </description> </method> + <method name="canvas_light_occluder_reset_physics_interpolation"> + <return type="void" /> + <param index="0" name="occluder" type="RID" /> + <description> + Prevents physics interpolation for the current physics tick. + This is useful when moving an occluder to a new location, to give an instantaneous change rather than interpolation from the previous location. + </description> + </method> <method name="canvas_light_occluder_set_as_sdf_collision"> <return type="void" /> <param index="0" name="occluder" type="RID" /> @@ -651,6 +692,14 @@ Enables or disables light occluder. </description> </method> + <method name="canvas_light_occluder_set_interpolated"> + <return type="void" /> + <param index="0" name="occluder" type="RID" /> + <param index="1" name="interpolated" type="bool" /> + <description> + If [param interpolated] is [code]true[/code], turns on physics interpolation for the light occluder. + </description> + </method> <method name="canvas_light_occluder_set_light_mask"> <return type="void" /> <param index="0" name="occluder" type="RID" /> @@ -675,6 +724,23 @@ Sets a light occluder's [Transform2D]. </description> </method> + <method name="canvas_light_occluder_transform_physics_interpolation"> + <return type="void" /> + <param index="0" name="occluder" type="RID" /> + <param index="1" name="transform" type="Transform2D" /> + <description> + Transforms both the current and previous stored transform for a light occluder. + This allows transforming an occluder without creating a "glitch" in the interpolation, which is particularly useful for large worlds utilising a shifting origin. + </description> + </method> + <method name="canvas_light_reset_physics_interpolation"> + <return type="void" /> + <param index="0" name="light" type="RID" /> + <description> + Prevents physics interpolation for the current physics tick. + This is useful when moving a canvas item to a new location, to give an instantaneous change rather than interpolation from the previous location. + </description> + </method> <method name="canvas_light_set_blend_mode"> <return type="void" /> <param index="0" name="light" type="RID" /> @@ -715,6 +781,14 @@ Sets a canvas light's height. </description> </method> + <method name="canvas_light_set_interpolated"> + <return type="void" /> + <param index="0" name="light" type="RID" /> + <param index="1" name="interpolated" type="bool" /> + <description> + If [param interpolated] is [code]true[/code], turns on physics interpolation for the canvas light. + </description> + </method> <method name="canvas_light_set_item_cull_mask"> <return type="void" /> <param index="0" name="light" type="RID" /> @@ -821,6 +895,15 @@ Sets the Z range of objects that will be affected by this light. Equivalent to [member Light2D.range_z_min] and [member Light2D.range_z_max]. </description> </method> + <method name="canvas_light_transform_physics_interpolation"> + <return type="void" /> + <param index="0" name="light" type="RID" /> + <param index="1" name="transform" type="Transform2D" /> + <description> + Transforms both the current and previous stored transform for a canvas light. + This allows transforming a light without creating a "glitch" in the interpolation, which is is particularly useful for large worlds utilising a shifting origin. + </description> + </method> <method name="canvas_occluder_polygon_create"> <return type="RID" /> <description> @@ -861,6 +944,15 @@ A copy of the canvas item will be drawn with a local offset of the mirroring [Vector2]. </description> </method> + <method name="canvas_set_item_repeat"> + <return type="void" /> + <param index="0" name="item" type="RID" /> + <param index="1" name="repeat_size" type="Vector2" /> + <param index="2" name="repeat_times" type="int" /> + <description> + A copy of the canvas item will be drawn with a local offset of the [param repeat_size] by the number of times of the [param repeat_times]. As the [param repeat_times] increases, the copies will spread away from the origin texture. + </description> + </method> <method name="canvas_set_modulate"> <return type="void" /> <param index="0" name="canvas" type="RID" /> @@ -918,6 +1010,54 @@ Sets the texture [param repeat] mode to use for the canvas texture specified by the [param canvas_texture] RID. </description> </method> + <method name="compositor_create"> + <return type="RID" /> + <description> + Creates a new compositor and adds it to the RenderingServer. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + </description> + </method> + <method name="compositor_effect_create"> + <return type="RID" /> + <description> + Creates a new rendering effect and adds it to the RenderingServer. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + </description> + </method> + <method name="compositor_effect_set_callback"> + <return type="void" /> + <param index="0" name="effect" type="RID" /> + <param index="1" name="callback_type" type="int" enum="RenderingServer.CompositorEffectCallbackType" /> + <param index="2" name="callback" type="Callable" /> + <description> + Sets the callback type ([param callback_type]) and callback method([param callback]) for this rendering effect. + </description> + </method> + <method name="compositor_effect_set_enabled"> + <return type="void" /> + <param index="0" name="effect" type="RID" /> + <param index="1" name="enabled" type="bool" /> + <description> + Enables/disables this rendering effect. + </description> + </method> + <method name="compositor_effect_set_flag"> + <return type="void" /> + <param index="0" name="effect" type="RID" /> + <param index="1" name="flag" type="int" enum="RenderingServer.CompositorEffectFlags" /> + <param index="2" name="set" type="bool" /> + <description> + Sets the flag ([param flag]) for this rendering effect to [code]true[/code] or [code]false[/code] ([param set]). + </description> + </method> + <method name="compositor_set_compositor_effects"> + <return type="void" /> + <param index="0" name="compositor" type="RID" /> + <param index="1" name="effects" type="RID[]" /> + <description> + Sets the compositor effects for the specified compositor RID. [param effects] should be an array containing RIDs created with [method compositor_effect_create]. + </description> + </method> <method name="create_local_rendering_device" qualifiers="const"> <return type="RenderingDevice" /> <description> @@ -925,6 +1065,14 @@ [b]Note:[/b] When using the OpenGL backend or when running in headless mode, this function always returns [code]null[/code]. </description> </method> + <method name="debug_canvas_item_get_rect"> + <return type="Rect2" /> + <param index="0" name="item" type="RID" /> + <description> + Returns the bounding rectangle for a canvas item in local space, as calculated by the renderer. This bound is used internally for culling. + [b]Warning:[/b] This function is intended for debugging in the editor, and will pass through and return a zero [Rect2] in exported projects. + </description> + </method> <method name="decal_create"> <return type="RID" /> <description> @@ -950,7 +1098,7 @@ Sets the cull [param mask] in the decal specified by the [param decal] RID. Equivalent to [member Decal.cull_mask]. </description> </method> - <method name="decal_set_distance_fade"> + <method name="decal_set_distance_fade" keywords="decal_set_lod"> <return type="void" /> <param index="0" name="decal" type="RID" /> <param index="1" name="enabled" type="bool" /> @@ -1137,6 +1285,7 @@ <param index="7" name="height_density" type="float" /> <param index="8" name="aerial_perspective" type="float" /> <param index="9" name="sky_affect" type="float" /> + <param index="10" name="fog_mode" type="int" enum="RenderingServer.EnvironmentFogMode" default="0" /> <description> Configures fog for the specified environment RID. See [code]fog_*[/code] properties in [Environment] for more information. </description> @@ -1362,7 +1511,7 @@ <param index="0" name="swap_buffers" type="bool" default="true" /> <param index="1" name="frame_step" type="float" default="0.0" /> <description> - Forces redrawing of all viewports at once. + Forces redrawing of all viewports at once. Must be called from the main thread. </description> </method> <method name="force_sync"> @@ -1548,11 +1697,11 @@ Returns [code]true[/code] if changes have been made to the RenderingServer's data. [method force_draw] is usually called if this happens. </description> </method> - <method name="has_feature" qualifiers="const"> + <method name="has_feature" qualifiers="const" deprecated="This method has not been used since Godot 3.0."> <return type="bool" /> <param index="0" name="feature" type="int" enum="RenderingServer.Features" /> <description> - Not yet implemented. Always returns [code]false[/code]. + This method does nothing and always returns [code]false[/code]. </description> </method> <method name="has_os_feature" qualifiers="const"> @@ -1893,7 +2042,7 @@ Sets the cull mask for this 3D light. Lights only affect objects in the selected layers. Equivalent to [member Light3D.light_cull_mask]. </description> </method> - <method name="light_set_distance_fade"> + <method name="light_set_distance_fade" keywords="light_set_lod"> <return type="void" /> <param index="0" name="decal" type="RID" /> <param index="1" name="enabled" type="bool" /> @@ -1929,7 +2078,7 @@ Sets the specified 3D light parameter. See [enum LightParam] for options. Equivalent to [method Light3D.set_param]. </description> </method> - <method name="light_set_projector"> + <method name="light_set_projector" keywords="light_set_cookie"> <return type="void" /> <param index="0" name="light" type="RID" /> <param index="1" name="texture" type="RID" /> @@ -2320,10 +2469,17 @@ <return type="PackedFloat32Array" /> <param index="0" name="multimesh" type="RID" /> <description> - Returns the MultiMesh data (such as instance transforms, colors, etc). See [method multimesh_set_buffer] for a description of the returned data. + Returns the MultiMesh data (such as instance transforms, colors, etc.). See [method multimesh_set_buffer] for details on the returned data. [b]Note:[/b] If the buffer is in the engine's internal cache, it will have to be fetched from GPU memory and possibly decompressed. This means [method multimesh_get_buffer] is potentially a slow operation and should be avoided whenever possible. </description> </method> + <method name="multimesh_get_custom_aabb" qualifiers="const"> + <return type="AABB" /> + <param index="0" name="multimesh" type="RID" /> + <description> + Returns the custom AABB defined for this MultiMesh resource. + </description> + </method> <method name="multimesh_get_instance_count" qualifiers="const"> <return type="int" /> <param index="0" name="multimesh" type="RID" /> @@ -2434,6 +2590,14 @@ [/codeblock] </description> </method> + <method name="multimesh_set_custom_aabb"> + <return type="void" /> + <param index="0" name="multimesh" type="RID" /> + <param index="1" name="aabb" type="AABB" /> + <description> + Sets the custom AABB for this MultiMesh resource. + </description> + </method> <method name="multimesh_set_mesh"> <return type="void" /> <param index="0" name="multimesh" type="RID" /> @@ -2886,7 +3050,7 @@ <param index="0" name="probe" type="RID" /> <param index="1" name="layers" type="int" /> <description> - Sets the render cull mask for this reflection probe. Only instances with a matching cull mask will be rendered by this probe. Equivalent to [member ReflectionProbe.cull_mask]. + Sets the render cull mask for this reflection probe. Only instances with a matching layer will be reflected by this probe. Equivalent to [member ReflectionProbe.cull_mask]. </description> </method> <method name="reflection_probe_set_enable_box_projection"> @@ -2937,6 +3101,14 @@ Sets the origin offset to be used when this reflection probe is in box project mode. Equivalent to [member ReflectionProbe.origin_offset]. </description> </method> + <method name="reflection_probe_set_reflection_mask"> + <return type="void" /> + <param index="0" name="probe" type="RID" /> + <param index="1" name="layers" type="int" /> + <description> + Sets the render reflection mask for this reflection probe. Only instances with a matching layer will have reflections applied from this probe. Equivalent to [member ReflectionProbe.reflection_mask]. + </description> + </method> <method name="reflection_probe_set_resolution"> <return type="void" /> <param index="0" name="probe" type="RID" /> @@ -2984,6 +3156,14 @@ Sets the camera attributes ([param effects]) that will be used with this scenario. See also [CameraAttributes]. </description> </method> + <method name="scenario_set_compositor"> + <return type="void" /> + <param index="0" name="scenario" type="RID" /> + <param index="1" name="compositor" type="RID" /> + <description> + Sets the compositor ([param compositor]) that will be used with this scenario. See also [Compositor]. + </description> + </method> <method name="scenario_set_environment"> <return type="void" /> <param index="0" name="scenario" type="RID" /> @@ -3329,7 +3509,7 @@ <return type="int" enum="Image.Format" /> <param index="0" name="texture" type="RID" /> <description> - Returns the [enum Image.Format] for the texture. + Returns the format for the texture. </description> </method> <method name="texture_get_native_handle" qualifiers="const"> @@ -3355,19 +3535,19 @@ Returns a texture [RID] that can be used with [RenderingDevice]. </description> </method> - <method name="texture_proxy_create" is_deprecated="true"> + <method name="texture_proxy_create" deprecated="ProxyTexture was removed in Godot 4."> <return type="RID" /> <param index="0" name="base" type="RID" /> <description> - [i]Deprecated.[/i] ProxyTexture was removed in Godot 4, so this method does nothing when called and always returns a null [RID]. + This method does nothing and always returns an invalid [RID]. </description> </method> - <method name="texture_proxy_update" is_deprecated="true"> + <method name="texture_proxy_update" deprecated="ProxyTexture was removed in Godot 4."> <return type="void" /> <param index="0" name="texture" type="RID" /> <param index="1" name="proxy_to" type="RID" /> <description> - [i]Deprecated.[/i] ProxyTexture was removed in Godot 4, so this method cannot be used anymore. + This method does nothing. </description> </method> <method name="texture_rd_create"> @@ -3504,12 +3684,20 @@ Returns the viewport's last rendered frame. </description> </method> + <method name="viewport_get_update_mode" qualifiers="const"> + <return type="int" enum="RenderingServer.ViewportUpdateMode" /> + <param index="0" name="viewport" type="RID" /> + <description> + Returns the viewport's update mode. See [enum ViewportUpdateMode] constants for options. + [b]Warning:[/b] Calling this from any thread other than the rendering thread will be detrimental to performance. + </description> + </method> <method name="viewport_remove_canvas"> <return type="void" /> <param index="0" name="viewport" type="RID" /> <param index="1" name="canvas" type="RID" /> <description> - Detaches a viewport from a canvas and vice versa. + Detaches a viewport from a canvas. </description> </method> <method name="viewport_set_active"> @@ -3798,7 +3986,7 @@ <param index="0" name="viewport" type="RID" /> <param index="1" name="enabled" type="bool" /> <description> - If [code]true[/code], 2D rendering will use a high dynamic range (HDR) format framebuffer matching the bit depth of the 3D framebuffer. When using the Forward+ renderer this will be a [code]RGBA16[/code] framebuffer, while when using the Mobile renderer it will be a [code]RGB10_A2[/code] framebuffer. Additionally, 2D rendering will take place in linear color space and will be converted to sRGB space immediately before blitting to the screen (if the Viewport is attached to the screen). Practically speaking, this means that the end result of the Viewport will not be clamped into the [code]0-1[/code] range and can be used in 3D rendering without color space adjustments. This allows 2D rendering to take advantage of effects requiring high dynamic range (e.g. 2D glow) as well as substantially improves the appearance of effects requiring highly detailed gradients. This setting has the same effect as [member Viewport.use_hdr_2d]. + If [code]true[/code], 2D rendering will use a high dynamic range (HDR) format framebuffer matching the bit depth of the 3D framebuffer. When using the Forward+ renderer this will be an [code]RGBA16[/code] framebuffer, while when using the Mobile renderer it will be an [code]RGB10_A2[/code] framebuffer. Additionally, 2D rendering will take place in linear color space and will be converted to sRGB space immediately before blitting to the screen (if the Viewport is attached to the screen). Practically speaking, this means that the end result of the Viewport will not be clamped into the [code]0-1[/code] range and can be used in 3D rendering without color space adjustments. This allows 2D rendering to take advantage of effects requiring high dynamic range (e.g. 2D glow) as well as substantially improves the appearance of effects requiring highly detailed gradients. This setting has the same effect as [member Viewport.use_hdr_2d]. [b]Note:[/b] This setting will have no effect when using the GL Compatibility renderer as the GL Compatibility renderer always renders in low dynamic range for performance reasons. </description> </method> @@ -4028,8 +4216,7 @@ <constant name="MAX_GLOW_LEVELS" value="7"> The maximum number of glow levels that can be used with the glow post-processing effect. </constant> - <constant name="MAX_CURSORS" value="8" is_deprecated="true"> - [i]Deprecated.[/i] This constant is unused internally. + <constant name="MAX_CURSORS" value="8" deprecated="This constant is not used by the engine."> </constant> <constant name="MAX_2D_DIRECTIONAL_LIGHTS" value="8"> The maximum number of directional lights that can be rendered at a given time in 2D. @@ -4686,7 +4873,10 @@ <constant name="VIEWPORT_RENDER_INFO_TYPE_SHADOW" value="1" enum="ViewportRenderInfoType"> Shadow render pass. Objects will be rendered several times depending on the number of amounts of lights with shadows and the number of directional shadow splits. </constant> - <constant name="VIEWPORT_RENDER_INFO_TYPE_MAX" value="2" enum="ViewportRenderInfoType"> + <constant name="VIEWPORT_RENDER_INFO_TYPE_CANVAS" value="2" enum="ViewportRenderInfoType"> + Canvas item rendering. This includes all 2D rendering. + </constant> + <constant name="VIEWPORT_RENDER_INFO_TYPE_MAX" value="3" enum="ViewportRenderInfoType"> Represents the size of the [enum ViewportRenderInfoType] enum. </constant> <constant name="VIEWPORT_DEBUG_DRAW_DISABLED" value="0" enum="ViewportDebugDraw"> @@ -4798,6 +4988,38 @@ Uses the fast filtering algorithm to process the radiance map. In general this results in lower quality, but substantially faster run times. If you need better quality, but still need to update the sky every frame, consider turning on [member ProjectSettings.rendering/reflections/sky_reflections/fast_filter_high_quality]. [b]Note:[/b] The fast filtering algorithm is limited to 256×256 cubemaps, so [method sky_set_radiance_size] must be set to [code]256[/code]. Otherwise, a warning is printed and the overridden radiance size is ignored. </constant> + <constant name="COMPOSITOR_EFFECT_FLAG_ACCESS_RESOLVED_COLOR" value="1" enum="CompositorEffectFlags"> + The rendering effect requires the color buffer to be resolved if MSAA is enabled. + </constant> + <constant name="COMPOSITOR_EFFECT_FLAG_ACCESS_RESOLVED_DEPTH" value="2" enum="CompositorEffectFlags"> + The rendering effect requires the depth buffer to be resolved if MSAA is enabled. + </constant> + <constant name="COMPOSITOR_EFFECT_FLAG_NEEDS_MOTION_VECTORS" value="4" enum="CompositorEffectFlags"> + The rendering effect requires motion vectors to be produced. + </constant> + <constant name="COMPOSITOR_EFFECT_FLAG_NEEDS_ROUGHNESS" value="8" enum="CompositorEffectFlags"> + The rendering effect requires normals and roughness g-buffer to be produced (Forward+ only). + </constant> + <constant name="COMPOSITOR_EFFECT_FLAG_NEEDS_SEPARATE_SPECULAR" value="16" enum="CompositorEffectFlags"> + The rendering effect requires specular data to be separated out (Forward+ only). + </constant> + <constant name="COMPOSITOR_EFFECT_CALLBACK_TYPE_PRE_OPAQUE" value="0" enum="CompositorEffectCallbackType"> + The callback is called before our opaque rendering pass, but after depth prepass (if applicable). + </constant> + <constant name="COMPOSITOR_EFFECT_CALLBACK_TYPE_POST_OPAQUE" value="1" enum="CompositorEffectCallbackType"> + The callback is called after our opaque rendering pass, but before our sky is rendered. + </constant> + <constant name="COMPOSITOR_EFFECT_CALLBACK_TYPE_POST_SKY" value="2" enum="CompositorEffectCallbackType"> + 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). + </constant> + <constant name="COMPOSITOR_EFFECT_CALLBACK_TYPE_PRE_TRANSPARENT" value="3" enum="CompositorEffectCallbackType"> + The callback is called before our transparent rendering pass, but after our sky is rendered and we've created our back buffers. + </constant> + <constant name="COMPOSITOR_EFFECT_CALLBACK_TYPE_POST_TRANSPARENT" value="4" enum="CompositorEffectCallbackType"> + The callback is called after our transparent rendering pass, but before any build in post effects and output to our render target. + </constant> + <constant name="COMPOSITOR_EFFECT_CALLBACK_TYPE_ANY" value="-1" enum="CompositorEffectCallbackType"> + </constant> <constant name="ENV_BG_CLEAR_COLOR" value="0" enum="EnvironmentBG"> Use the clear color as background. </constant> @@ -4855,6 +5077,12 @@ <constant name="ENV_GLOW_BLEND_MODE_MIX" value="4" enum="EnvironmentGlowBlendMode"> Mixes the glow with the underlying color to avoid increasing brightness as much while still maintaining a glow effect. </constant> + <constant name="ENV_FOG_MODE_EXPONENTIAL" value="0" enum="EnvironmentFogMode"> + Use a physically-based fog model defined primarily by fog density. + </constant> + <constant name="ENV_FOG_MODE_DEPTH" value="1" enum="EnvironmentFogMode"> + Use a simple fog model defined by start and end positions and a custom curve. While not physically accurate, this model can be useful when you need more artistic control. + </constant> <constant name="ENV_TONE_MAPPER_LINEAR" value="0" enum="EnvironmentToneMapper"> Output color as they came in. This can cause bright lighting to look blown out, with noticeable clipping in the output colors. </constant> @@ -5087,13 +5315,13 @@ <constant name="SHADOW_CASTING_SETTING_SHADOWS_ONLY" value="3" enum="ShadowCastingSetting"> Only render the shadows from the object. The object itself will not be drawn. </constant> - <constant name="VISIBILITY_RANGE_FADE_DISABLED" value="0" enum="VisibilityRangeFadeMode"> + <constant name="VISIBILITY_RANGE_FADE_DISABLED" value="0" enum="VisibilityRangeFadeMode" keywords="LOD_FADE_DISABLED"> Disable visibility range fading for the given instance. </constant> - <constant name="VISIBILITY_RANGE_FADE_SELF" value="1" enum="VisibilityRangeFadeMode"> + <constant name="VISIBILITY_RANGE_FADE_SELF" value="1" enum="VisibilityRangeFadeMode" keywords="LOD_FADE_SELF"> Fade-out the given instance when it approaches its visibility range limits. </constant> - <constant name="VISIBILITY_RANGE_FADE_DEPENDENCIES" value="2" enum="VisibilityRangeFadeMode"> + <constant name="VISIBILITY_RANGE_FADE_DEPENDENCIES" value="2" enum="VisibilityRangeFadeMode" keywords="LOD_FADE_DEPENDENCIES"> Fade-in the given instance's dependencies when reaching its visibility range limits. </constant> <constant name="BAKE_CHANNEL_ALBEDO_ALPHA" value="0" enum="BakeChannels"> @@ -5130,22 +5358,26 @@ Uses the default filter mode for this [Viewport]. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_NEAREST" value="1" enum="CanvasItemTextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_LINEAR" value="2" enum="CanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="3" enum="CanvasItemTextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="4" enum="CanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC" value="5" enum="CanvasItemTextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC" value="6" enum="CanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_MAX" value="7" enum="CanvasItemTextureFilter"> Max value for [enum CanvasItemTextureFilter] enum. @@ -5317,11 +5549,9 @@ <constant name="RENDERING_INFO_VIDEO_MEM_USED" value="5" enum="RenderingInfo"> Video memory used (in bytes). When using the Forward+ or mobile rendering backends, this is always greater than the sum of [constant RENDERING_INFO_TEXTURE_MEM_USED] and [constant RENDERING_INFO_BUFFER_MEM_USED], since there is miscellaneous data not accounted for by those two metrics. When using the GL Compatibility backend, this is equal to the sum of [constant RENDERING_INFO_TEXTURE_MEM_USED] and [constant RENDERING_INFO_BUFFER_MEM_USED]. </constant> - <constant name="FEATURE_SHADERS" value="0" enum="Features"> - Hardware supports shaders. This enum is currently unused in Godot 3.x. + <constant name="FEATURE_SHADERS" value="0" enum="Features" deprecated="This constant has not been used since Godot 3.0."> </constant> - <constant name="FEATURE_MULTITHREADED" value="1" enum="Features"> - Hardware supports multithreading. This enum is currently unused in Godot 3.x. + <constant name="FEATURE_MULTITHREADED" value="1" enum="Features" deprecated="This constant has not been used since Godot 3.0."> </constant> </constants> </class> diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index c8146bb48f..cec936ac3e 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -4,9 +4,10 @@ Base class for serializable objects. </brief_description> <description> - Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from [RefCounted], resources are reference-counted and freed when no longer in use. They can also be nested within other resources, and saved on disk. Once loaded from disk, further attempts to load a resource by [member resource_path] returns the same reference. [PackedScene], one of the most common [Object]s in a Godot project, is also a resource, uniquely capable of storing and instantiating the [Node]s it contains as many times as desired. + Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from [RefCounted], resources are reference-counted and freed when no longer in use. They can also be nested within other resources, and saved on disk. [PackedScene], one of the most common [Object]s in a Godot project, is also a resource, uniquely capable of storing and instantiating the [Node]s it contains as many times as desired. In GDScript, resources can loaded from disk by their [member resource_path] using [method @GDScript.load] or [method @GDScript.preload]. - [b]Note:[/b] In C#, resources will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free resources that are no longer in use. This means that unused resources will linger on for a while before being removed. + The engine keeps a global cache of all loaded resources, referenced by paths (see [method ResourceLoader.has_cached]). A resource will be cached when loaded for the first time and removed from cache once all references are released. When a resource is cached, subsequent loads using its path will return the cached reference. + [b]Note:[/b] In C#, resources will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free resources that are no longer in use. This means that unused resources will remain in memory for a while before being removed. </description> <tutorials> <link title="Resources">$DOCS_URL/tutorials/scripting/resources.html</link> @@ -58,6 +59,12 @@ [/codeblock] </description> </method> + <method name="generate_scene_unique_id" qualifiers="static"> + <return type="String" /> + <description> + Generates a unique identifier for a resource to be contained inside a [PackedScene], based on the current date, time, and a random value. The returned string is only composed of letters ([code]a[/code] to [code]y[/code]) and numbers ([code]0[/code] to [code]8[/code]). See also [member resource_scene_unique_id]. + </description> + </method> <method name="get_local_scene" qualifiers="const"> <return type="Node" /> <description> @@ -70,11 +77,10 @@ Returns the [RID] of this resource (or an empty RID). Many resources (such as [Texture2D], [Mesh], and so on) are high-level abstractions of resources stored in a specialized server ([DisplayServer], [RenderingServer], etc.), so this function will return the original [RID]. </description> </method> - <method name="setup_local_to_scene" is_deprecated="true"> + <method name="setup_local_to_scene" deprecated="This method should only be called internally."> <return type="void" /> <description> Calls [method _setup_local_to_scene]. If [member resource_local_to_scene] is set to [code]true[/code], this method is automatically called from [method PackedScene.instantiate] by the newly duplicated resource within the scene instance. - [i]Deprecated.[/i] This method should only be called internally. Override [method _setup_local_to_scene] instead. </description> </method> <method name="take_over_path"> @@ -98,6 +104,12 @@ The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the [PackedScene]'s filepath, followed by a unique identifier. [b]Note:[/b] Setting this property manually may fail if a resource with the same path has already been previously loaded. If necessary, use [method take_over_path]. </member> + <member name="resource_scene_unique_id" type="String" setter="set_scene_unique_id" getter="get_scene_unique_id"> + An unique identifier relative to the this resource's scene. If left empty, the ID is automatically generated when this resource is saved inside a [PackedScene]. If the resource is not inside a scene, this property is empty by default. + [b]Note:[/b] When the [PackedScene] is saved, if multiple resources in the same scene use the same ID, only the earliest resource in the scene hierarchy keeps the original ID. The other resources are assigned new IDs from [method generate_scene_unique_id]. + [b]Note:[/b] Setting this property does not emit the [signal changed] signal. + [b]Warning:[/b] When setting, the ID must only consist of letters, numbers, and underscores. Otherwise, it will fail and default to a randomly generated ID. + </member> </members> <signals> <signal name="changed"> @@ -106,10 +118,9 @@ [b]Note:[/b] This signal is not emitted automatically for properties of custom resources. If necessary, a setter needs to be created to emit the signal. </description> </signal> - <signal name="setup_local_to_scene_requested" is_deprecated="true"> + <signal name="setup_local_to_scene_requested" deprecated="This signal is only emitted when the resource is created. Override [method _setup_local_to_scene] instead."> <description> - Emitted by a newly duplicated resource with [member resource_local_to_scene] set to [code]true[/code]. - [i]Deprecated.[/i] This signal is only emitted when the resource is created. Override [method _setup_local_to_scene] instead. + Emitted by a newly duplicated resource with [member resource_local_to_scene] set to [code]true[/code]. </description> </signal> </signals> diff --git a/doc/classes/ResourceFormatLoader.xml b/doc/classes/ResourceFormatLoader.xml index 61eafb4527..4e4adc86c4 100644 --- a/doc/classes/ResourceFormatLoader.xml +++ b/doc/classes/ResourceFormatLoader.xml @@ -99,10 +99,19 @@ </methods> <constants> <constant name="CACHE_MODE_IGNORE" value="0" enum="CacheMode"> + Neither the main resource (the one requested to be loaded) nor any of its subresources are retrieved from cache nor stored into it. Dependencies (external resources) are loaded with [constant CACHE_MODE_REUSE]. </constant> <constant name="CACHE_MODE_REUSE" value="1" enum="CacheMode"> + The main resource (the one requested to be loaded), its subresources, and its dependencies (external resources) are retrieved from cache if present, instead of loaded. Those not cached are loaded and then stored into the cache. The same rules are propagated recursively down the tree of dependencies (external resources). </constant> <constant name="CACHE_MODE_REPLACE" value="2" enum="CacheMode"> + Like [constant CACHE_MODE_REUSE], but the cache is checked for the main resource (the one requested to be loaded) as well as for each of its subresources. Those already in the cache, as long as the loaded and cached types match, have their data refreshed from storage into the already existing instances. Otherwise, they are recreated as completely new objects. + </constant> + <constant name="CACHE_MODE_IGNORE_DEEP" value="3" enum="CacheMode"> + Like [constant CACHE_MODE_IGNORE], but propagated recursively down the tree of dependencies (external resources). + </constant> + <constant name="CACHE_MODE_REPLACE_DEEP" value="4" enum="CacheMode"> + Like [constant CACHE_MODE_REPLACE], but propagated recursively down the tree of dependencies (external resources). </constant> </constants> </class> diff --git a/doc/classes/ResourceImporterDynamicFont.xml b/doc/classes/ResourceImporterDynamicFont.xml index 437b3c8a96..f100670e08 100644 --- a/doc/classes/ResourceImporterDynamicFont.xml +++ b/doc/classes/ResourceImporterDynamicFont.xml @@ -25,6 +25,9 @@ <member name="compress" type="bool" setter="" getter="" default="true"> If [code]true[/code], uses lossless compression for the resulting font. </member> + <member name="disable_embedded_bitmaps" type="bool" setter="" getter="" default="true"> + If set to [code]true[/code], embedded font bitmap loading is disabled (bitmap-only and color fonts ignore this property). + </member> <member name="fallbacks" type="Array" setter="" getter="" default="[]"> List of font fallbacks to use if a glyph isn't found in this dynamic font. Fonts at the beginning of the array are attempted first, but fallback fonts that don't support the glyph's language and script are attempted last (see [member language_support] and [member script_support]). See also [member allow_system_fallback]. </member> diff --git a/doc/classes/ResourceImporterImageFont.xml b/doc/classes/ResourceImporterImageFont.xml index 481a6757d5..afc791f874 100644 --- a/doc/classes/ResourceImporterImageFont.xml +++ b/doc/classes/ResourceImporterImageFont.xml @@ -11,12 +11,16 @@ <link title="Bitmap fonts - Using fonts">$DOCS_URL/tutorials/ui/gui_using_fonts.html#bitmap-fonts</link> </tutorials> <members> + <member name="ascent" type="int" setter="" getter="" default="0"> + Font ascent (number of pixels above the baseline). If set to [code]0[/code], half of the character height is used. + </member> <member name="character_margin" type="Rect2i" setter="" getter="" default="Rect2i(0, 0, 0, 0)"> Margin applied around every imported glyph. If your font image contains guides (in the form of lines between glyphs) or if spacing between characters appears incorrect, try adjusting [member character_margin]. </member> <member name="character_ranges" type="PackedStringArray" setter="" getter="" default="PackedStringArray()"> - The character ranges to import from the font image. This is an array that maps each position on the image (in tile coordinates, not pixels). The font atlas is traversed from left to right and top to bottom. Characters can be specified with decimal numbers (127), hexadecimal numbers ([code]0x007f[/code]) or between single quotes ([code]'~'[/code]). Ranges can be specified with a hyphen between characters. - For instance, [code]0-127[/code] (or [code]0x0000-0x007f[/code]) denotes the full ASCII range. As another example, [code]' '-'~'[/code] is equivalent to [code]32-127[/code] and denotes the range of printable (visible) ASCII characters. + The character ranges to import from the font image. This is an array that maps each position on the image (in tile coordinates, not pixels). The font atlas is traversed from left to right and top to bottom. Characters can be specified with decimal numbers (127), hexadecimal numbers ([code]0x007f[/code], or [code]U+007f[/code]) or between single quotes ([code]'~'[/code]). Ranges can be specified with a hyphen between characters. + For example, [code]0-127[/code] represents the full ASCII range. It can also be written as [code]0x0000-0x007f[/code] (or [code]U+0000-U+007f[/code]). As another example, [code]' '-'~'[/code] is equivalent to [code]32-127[/code] and represents the range of printable (visible) ASCII characters. + For any range, the character advance and offset can be customized by appending three space-separated integer values (additional advance, x offset, y offset) to the end. For example [code]'a'-'b' 4 5 2[/code] sets the advance to [code]char_width + 4[/code] and offset to [code]Vector2(5, 2)[/code] for both `a` and `b` characters. Make sure [member character_ranges] doesn't exceed the number of [member columns] * [member rows] defined. Otherwise, the font will fail to import. </member> <member name="columns" type="int" setter="" getter="" default="1"> @@ -25,12 +29,19 @@ <member name="compress" type="bool" setter="" getter="" default="true"> If [code]true[/code], uses lossless compression for the resulting font. </member> + <member name="descent" type="int" setter="" getter="" default="0"> + Font descent (number of pixels below the baseline). If set to [code]0[/code], half of the character height is used. + </member> <member name="fallbacks" type="Array" setter="" getter="" default="[]"> List of font fallbacks to use if a glyph isn't found in this bitmap font. Fonts at the beginning of the array are attempted first. </member> <member name="image_margin" type="Rect2i" setter="" getter="" default="Rect2i(0, 0, 0, 0)"> Margin to cut on the sides of the entire image. This can be used to cut parts of the image that contain attribution information or similar. </member> + <member name="kerning_pairs" type="PackedStringArray" setter="" getter="" default="PackedStringArray()"> + Kerning pairs for the font. Kerning pair adjust the spacing between two characters. + Each string consist of three space separated values: "from" string, "to" string and integer offset. Each combination form the two string for a kerning pair, e.g, [code]ab cd -3[/code] will create kerning pairs [code]ac[/code], [code]ad[/code], [code]bc[/code], and [code]bd[/code] with offset [code]-3[/code]. + </member> <member name="rows" type="int" setter="" getter="" default="1"> Number of rows in the font image. See also [member columns]. </member> diff --git a/doc/classes/ResourceImporterOBJ.xml b/doc/classes/ResourceImporterOBJ.xml index fa964e5016..55043a311c 100644 --- a/doc/classes/ResourceImporterOBJ.xml +++ b/doc/classes/ResourceImporterOBJ.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="ResourceImporterOBJ" inherits="ResourceImporter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Imports an OBJ 3D model as a standalone [Mesh] or scene. + Imports an OBJ 3D model as an independent [Mesh] or scene. </brief_description> <description> Unlike [ResourceImporterScene], [ResourceImporterOBJ] will import a single [Mesh] resource by default instead of importing a [PackedScene]. This makes it easier to use the [Mesh] resource in nodes that expect direct [Mesh] resources, such as [GridMap], [GPUParticles3D] or [CPUParticles3D]. Note that it is still possible to save mesh resources from 3D scenes using the [b]Advanced Import Settings[/b] dialog, regardless of the source format. diff --git a/doc/classes/ResourceImporterScene.xml b/doc/classes/ResourceImporterScene.xml index 1769da9f24..900e028b25 100644 --- a/doc/classes/ResourceImporterScene.xml +++ b/doc/classes/ResourceImporterScene.xml @@ -4,7 +4,7 @@ Imports a glTF, FBX, Collada or Blender 3D scene. </brief_description> <description> - See also [ResourceImporterOBJ], which is used for OBJ models that can be imported as a standalone [Mesh] or a scene. + See also [ResourceImporterOBJ], which is used for OBJ models that can be imported as an independent [Mesh] or a scene. Additional options (such as extracting individual meshes or materials to files) are available in the [b]Advanced Import Settings[/b] dialog. This dialog can be accessed by double-clicking a 3D scene in the FileSystem dock or by selecting a 3D scene in the FileSystem dock, going to the Import dock and choosing [b]Advanced[/b]. [b]Note:[/b] [ResourceImporterScene] is [i]not[/i] used for [PackedScene]s, such as [code].tscn[/code] and [code].scn[/code] files. </description> @@ -21,6 +21,9 @@ <member name="animation/import" type="bool" setter="" getter="" default="true"> If [code]true[/code], import animations from the 3D scene. </member> + <member name="animation/import_rest_as_RESET" type="bool" setter="" getter="" default="false"> + If [code]true[/code], adds an [Animation] named [code]RESET[/code], containing the [method Skeleton3D.get_bone_rest] from [Skeleton3D] nodes. This can be useful to extract an animation in the reference pose. + </member> <member name="animation/remove_immutable_tracks" type="bool" setter="" getter="" default="true"> If [code]true[/code], remove animation tracks that only contain default values. This can reduce output file size and memory usage with certain 3D scenes, depending on the contents of their animation tracks. </member> @@ -53,6 +56,9 @@ <member name="nodes/apply_root_scale" type="bool" setter="" getter="" default="true"> If [code]true[/code], [member nodes/root_scale] will be applied to the descendant nodes, meshes, animations, bones, etc. This means that if you add a child node later on within the imported scene, it won't be scaled. If [code]false[/code], [member nodes/root_scale] will multiply the scale of the root node instead. </member> + <member name="nodes/import_as_skeleton_bones" type="bool" setter="" getter="" default="false"> + Treat all nodes in the imported scene as if they are bones within a single [Skeleton3D]. Can be used to guarantee that imported animations target skeleton bones rather than nodes. May also be used to assign the [code]"Root"[/code] bone in a [BoneMap]. See [url=$DOCS_URL/tutorials/assets_pipeline/retargeting_3d_skeletons.html]Retargeting 3D Skeletons[/url] for more information. + </member> <member name="nodes/root_name" type="String" setter="" getter="" default=""""> Override for the root node name. If empty, the root node will use what the scene specifies, or the file name if the scene does not specify a root name. </member> diff --git a/doc/classes/ResourceImporterTexture.xml b/doc/classes/ResourceImporterTexture.xml index b6669b8293..678aa2101c 100644 --- a/doc/classes/ResourceImporterTexture.xml +++ b/doc/classes/ResourceImporterTexture.xml @@ -66,7 +66,7 @@ Unimplemented. This currently has no effect when changed. </member> <member name="process/fix_alpha_border" type="bool" setter="" getter="" default="true"> - If [code]true[/code], puts pixels of the same surrounding color in transition from transparent to opaque areas. For textures displayed with bilinear filtering, this helps mitigate the outline effect when exporting images from an image editor. + If [code]true[/code], puts pixels of the same surrounding color in transition from transparent to opaque areas. For textures displayed with bilinear filtering, this helps to reduce the outline effect when exporting images from an image editor. It's recommended to leave this enabled (as it is by default), unless this causes issues for a particular image. </member> <member name="process/hdr_as_srgb" type="bool" setter="" getter="" default="false"> diff --git a/doc/classes/ResourceLoader.xml b/doc/classes/ResourceLoader.xml index 267594edcb..95fbee4a24 100644 --- a/doc/classes/ResourceLoader.xml +++ b/doc/classes/ResourceLoader.xml @@ -28,6 +28,7 @@ <description> Returns whether a recognized resource exists for the given [param path]. An optional [param type_hint] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader]. Anything that inherits from [Resource] can be used as a type hint, for example [Image]. + [b]Note:[/b] If you use [method Resource.take_over_path], this method will return [code]true[/code] for the taken path even if the resource wasn't saved (i.e. exists only in resource cache). </description> </method> <method name="get_dependencies"> @@ -137,10 +138,19 @@ The resource was loaded successfully and can be accessed via [method load_threaded_get]. </constant> <constant name="CACHE_MODE_IGNORE" value="0" enum="CacheMode"> + Neither the main resource (the one requested to be loaded) nor any of its subresources are retrieved from cache nor stored into it. Dependencies (external resources) are loaded with [constant CACHE_MODE_REUSE]. </constant> <constant name="CACHE_MODE_REUSE" value="1" enum="CacheMode"> + The main resource (the one requested to be loaded), its subresources, and its dependencies (external resources) are retrieved from cache if present, instead of loaded. Those not cached are loaded and then stored into the cache. The same rules are propagated recursively down the tree of dependencies (external resources). </constant> <constant name="CACHE_MODE_REPLACE" value="2" enum="CacheMode"> + Like [constant CACHE_MODE_REUSE], but the cache is checked for the main resource (the one requested to be loaded) as well as for each of its subresources. Those already in the cache, as long as the loaded and cached types match, have their data refreshed from storage into the already existing instances. Otherwise, they are recreated as completely new objects. + </constant> + <constant name="CACHE_MODE_IGNORE_DEEP" value="3" enum="CacheMode"> + Like [constant CACHE_MODE_IGNORE], but propagated recursively down the tree of dependencies (external resources). + </constant> + <constant name="CACHE_MODE_REPLACE_DEEP" value="4" enum="CacheMode"> + Like [constant CACHE_MODE_REPLACE], but propagated recursively down the tree of dependencies (external resources). </constant> </constants> </class> diff --git a/doc/classes/RichTextEffect.xml b/doc/classes/RichTextEffect.xml index ca95557f1b..774fa2bf9c 100644 --- a/doc/classes/RichTextEffect.xml +++ b/doc/classes/RichTextEffect.xml @@ -4,7 +4,7 @@ A custom effect for a [RichTextLabel]. </brief_description> <description> - A custom effect for a [RichTextLabel]. + A custom effect for a [RichTextLabel], which can be loaded in the [RichTextLabel] inspector or using [method RichTextLabel.install_effect]. [b]Note:[/b] For a [RichTextEffect] to be usable, a BBCode tag must be defined as a member variable called [code]bbcode[/code] in the script. [codeblocks] [gdscript skip-lint] diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index c9a48e46b2..b9a6b06fe3 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -55,8 +55,8 @@ <method name="clear"> <return type="void" /> <description> - Clears the tag stack. - [b]Note:[/b] This method will not modify [member text], but setting [member text] to an empty string also clears the stack. + Clears the tag stack, causing the label to display nothing. + [b]Note:[/b] This method does not affect [member text], and its contents will show again if the label is redrawn. However, setting [member text] to an empty [String] also clears the stack. </description> </method> <method name="deselect"> @@ -69,7 +69,7 @@ <return type="int" /> <param index="0" name="character" type="int" /> <description> - Returns the line number of the character position provided. + Returns the line number of the character position provided. Line and character numbers are both zero-indexed. [b]Note:[/b] If [member threaded] is enabled, this method returns a value for the loaded part of the document. Use [method is_ready] or [signal finished] to determine whether document is fully loaded. </description> </method> @@ -77,7 +77,7 @@ <return type="int" /> <param index="0" name="character" type="int" /> <description> - Returns the paragraph number of the character position provided. + Returns the paragraph number of the character position provided. Paragraph and character numbers are both zero-indexed. [b]Note:[/b] If [member threaded] is enabled, this method returns a value for the loaded part of the document. Use [method is_ready] or [signal finished] to determine whether document is fully loaded. </description> </method> @@ -225,7 +225,28 @@ <return type="void" /> <param index="0" name="effect" type="Variant" /> <description> - Installs a custom effect. [param effect] should be a valid [RichTextEffect]. + Installs a custom effect. This can also be done in the RichTextLabel inspector using the [member custom_effects] property. [param effect] should be a valid [RichTextEffect]. + Example RichTextEffect: + [codeblock] + # effect.gd + class_name MyCustomEffect + extends RichTextEffect + + var bbcode = "my_custom_effect" + + # ... + [/codeblock] + Registering the above effect in RichTextLabel from script: + [codeblock] + # rich_text_label.gd + extends RichTextLabel + + func _ready(): + install_effect(MyCustomEffect.new()) + + # Alternatively, if not using `class_name` in the script that extends RichTextEffect: + install_effect(preload("res://effect.gd").new()) + [/codeblock] </description> </method> <method name="is_menu_visible" qualifiers="const"> @@ -407,8 +428,11 @@ <method name="push_meta"> <return type="void" /> <param index="0" name="data" type="Variant" /> + <param index="1" name="underline_mode" type="int" enum="RichTextLabel.MetaUnderline" default="1" /> <description> Adds a meta tag to the tag stack. Similar to the BBCode [code skip-lint][url=something]{text}[/url][/code], but supports non-[String] metadata types. + If [member meta_underlined] is [code]true[/code], meta tags display an underline. This behavior can be customized with [param underline_mode]. + [b]Note:[/b] Meta tags do nothing by default when clicked. To assign behavior when clicked, connect [signal meta_clicked] to a function that is called when the meta tag is clicked. </description> </method> <method name="push_mono"> @@ -570,6 +594,7 @@ </member> <member name="bbcode_enabled" type="bool" setter="set_use_bbcode" getter="is_using_bbcode" default="false"> If [code]true[/code], the label uses BBCode formatting. + [b]Note:[/b] This only affects the contents of [member text], not the tag stack. </member> <member name="clip_contents" type="bool" setter="set_clip_contents" getter="is_clipping_contents" overrides="Control" default="true" /> <member name="context_menu_enabled" type="bool" setter="set_context_menu_enabled" getter="is_context_menu_enabled" default="false"> @@ -595,7 +620,7 @@ Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead. </member> <member name="meta_underlined" type="bool" setter="set_meta_underline" getter="is_meta_underlined" default="true"> - If [code]true[/code], the label underlines meta tags such as [code skip-lint][url]{text}[/url][/code]. + If [code]true[/code], the label underlines meta tags such as [code skip-lint][url]{text}[/url][/code]. These tags can call a function when clicked if [signal meta_clicked] is connected to a function. </member> <member name="progress_bar_delay" type="int" setter="set_progress_bar_delay" getter="get_progress_bar_delay" default="1000"> The delay after which the loading progress bar is displayed, in milliseconds. Set to [code]-1[/code] to disable progress bar entirely. @@ -653,7 +678,17 @@ <signal name="meta_clicked"> <param index="0" name="meta" type="Variant" /> <description> - Triggered when the user clicks on content between meta tags. If the meta is defined in text, e.g. [code skip-lint][url={"data"="hi"}]hi[/url][/code], then the parameter for this signal will be a [String] type. If a particular type or an object is desired, the [method push_meta] method must be used to manually insert the data into the tag stack. + Triggered when the user clicks on content between meta (URL) tags. If the meta is defined in BBCode, e.g. [code skip-lint][url={"key": "value"}]Text[/url][/code], then the parameter for this signal will always be a [String] type. If a particular type or an object is desired, the [method push_meta] method must be used to manually insert the data into the tag stack. Alternatively, you can convert the [String] input to the desired type based on its contents (such as calling [method JSON.parse] on it). + For example, the following method can be connected to [signal meta_clicked] to open clicked URLs using the user's default web browser: + [codeblocks] + [gdscript] + # This assumes RichTextLabel's `meta_clicked` signal was connected to + # the function below using the signal connection dialog. + func _richtextlabel_on_meta_clicked(meta): + # `meta` is of Variant type, so convert it to a String to avoid script errors at run-time. + OS.shell_open(str(meta)) + [/gdscript] + [/codeblocks] </description> </signal> <signal name="meta_hover_ended"> @@ -691,6 +726,15 @@ <constant name="MENU_MAX" value="2" enum="MenuItems"> Represents the size of the [enum MenuItems] enum. </constant> + <constant name="META_UNDERLINE_NEVER" value="0" enum="MetaUnderline"> + Meta tag does not display an underline, even if [member meta_underlined] is [code]true[/code]. + </constant> + <constant name="META_UNDERLINE_ALWAYS" value="1" enum="MetaUnderline"> + If [member meta_underlined] is [code]true[/code], meta tag always display an underline. + </constant> + <constant name="META_UNDERLINE_ON_HOVER" value="2" enum="MetaUnderline"> + If [member meta_underlined] is [code]true[/code], meta tag display an underline when the mouse cursor is over it. + </constant> <constant name="UPDATE_TEXTURE" value="1" enum="ImageUpdateMask" is_bitfield="true"> If this bit is set, [method update_image] changes image texture. </constant> @@ -720,7 +764,7 @@ <theme_item name="default_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> The default text color. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The default tint of text outline. </theme_item> <theme_item name="font_selected_color" data_type="color" type="Color" default="Color(0, 0, 0, 0)"> diff --git a/doc/classes/RootMotionView.xml b/doc/classes/RootMotionView.xml index 648ea04a7d..d7fbb2d80d 100644 --- a/doc/classes/RootMotionView.xml +++ b/doc/classes/RootMotionView.xml @@ -17,7 +17,7 @@ <member name="cell_size" type="float" setter="set_cell_size" getter="get_cell_size" default="1.0"> The grid's cell size in 3D units. </member> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0.5, 0.5, 1, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0.5, 0.5, 1, 1)" keywords="colour"> The grid's color. </member> <member name="radius" type="float" setter="set_radius" getter="get_radius" default="10.0"> diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml index da23eadfd1..bae5fe1205 100644 --- a/doc/classes/SceneTree.xml +++ b/doc/classes/SceneTree.xml @@ -4,9 +4,9 @@ Manages the game loop via a hierarchy of nodes. </brief_description> <description> - As one of the most important classes, the [SceneTree] manages the hierarchy of nodes in a scene as well as scenes themselves. Nodes can be added, retrieved and removed. The whole scene tree (and thus the current scene) can be paused. Scenes can be loaded, switched and reloaded. - You can also use the [SceneTree] to organize your nodes into groups: every node can be assigned as many groups as you want to create, e.g. an "enemy" group. You can then iterate these groups or even call methods and set properties on all the group's members at once. - [SceneTree] is the default [MainLoop] implementation used by scenes, and is thus in charge of the game loop. + As one of the most important classes, the [SceneTree] manages the hierarchy of nodes in a scene, as well as scenes themselves. Nodes can be added, fetched and removed. The whole scene tree (and thus the current scene) can be paused. Scenes can be loaded, switched and reloaded. + You can also use the [SceneTree] to organize your nodes into [b]groups[/b]: every node can be added to as many groups as you want to create, e.g. an "enemy" group. You can then iterate these groups or even call methods and set properties on all the nodes belonging to any given group. + [SceneTree] is the default [MainLoop] implementation used by the engine, and is thus in charge of the game loop. </description> <tutorials> <link title="SceneTree">$DOCS_URL/tutorials/scripting/scene_tree.html</link> @@ -18,8 +18,9 @@ <param index="0" name="group" type="StringName" /> <param index="1" name="method" type="StringName" /> <description> - Calls [param method] on each member of the given group. You can pass arguments to [param method] by specifying them at the end of the method call. If a node doesn't have the given method or the argument list does not match (either in count or in types), it will be skipped. - [b]Note:[/b] [method call_group] will call methods immediately on all members at once, which can cause stuttering if an expensive method is called on lots of members. + Calls [param method] on each node inside this tree added to the given [param group]. You can pass arguments to [param method] by specifying them at the end of this method call. Nodes that cannot call [param method] (either because the method doesn't exist or the arguments do not match) are ignored. See also [method set_group] and [method notify_group]. + [b]Note:[/b] This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="call_group_flags" qualifiers="vararg"> @@ -28,12 +29,14 @@ <param index="1" name="group" type="StringName" /> <param index="2" name="method" type="StringName" /> <description> - Calls [param method] on each member of the given group, respecting the given [enum GroupCallFlags]. You can pass arguments to [param method] by specifying them at the end of the method call. If a node doesn't have the given method or the argument list does not match (either in count or in types), it will be skipped. + Calls the given [param method] on each node inside this tree added to the given [param group]. Use [param flags] to customize this method's behavior (see [enum GroupCallFlags]). Additional arguments for [param method] can be passed at the end of this method. Nodes that cannot call [param method] (either because the method doesn't exist or the arguments do not match) are ignored. [codeblock] - # Call the method in a deferred manner and in reverse order. - get_tree().call_group_flags(SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE) + # Calls "hide" to all nodes of the "enemies" group, at the end of the frame and in reverse tree order. + get_tree().call_group_flags( + SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE, + "enemies", "hide") [/codeblock] - [b]Note:[/b] Group call flags are used to control the method calling behavior. By default, methods will be called immediately in a way similar to [method call_group]. However, if the [constant GROUP_CALL_DEFERRED] flag is present in the [param flags] argument, methods will be called at the end of the frame in a way similar to [method Object.set_deferred]. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="change_scene_to_file"> @@ -42,7 +45,7 @@ <description> Changes the running scene to the one at the given [param path], after loading it into a [PackedScene] and creating a new instance. Returns [constant OK] on success, [constant ERR_CANT_OPEN] if the [param path] cannot be loaded into a [PackedScene], or [constant ERR_CANT_CREATE] if that scene cannot be instantiated. - [b]Note:[/b] The new scene node is added to the tree at the end of the frame. This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to [method Node.queue_free]. As such, you won't be able to access the loaded scene immediately after the [method change_scene_to_file] call. + [b]Note:[/b] See [method change_scene_to_packed] for details on the order of operations. </description> </method> <method name="change_scene_to_packed"> @@ -51,7 +54,10 @@ <description> Changes the running scene to a new instance of the given [PackedScene] (which must be valid). Returns [constant OK] on success, [constant ERR_CANT_CREATE] if the scene cannot be instantiated, or [constant ERR_INVALID_PARAMETER] if the scene is invalid. - [b]Note:[/b] The new scene node is added to the tree at the end of the frame. You won't be able to access it immediately after the [method change_scene_to_packed] call. + [b]Note:[/b] Operations happen in the following order when [method change_scene_to_packed] is called: + 1. The current scene node is immediately removed from the tree. From that point, [method Node.get_tree] called on the current (outgoing) scene will return [code]null[/code]. [member current_scene] will be [code]null[/code], too, because the new scene is not available yet. + 2. At the end of the frame, the formerly current scene, already removed from the tree, will be deleted (freed from memory) and then the new scene will be instantiated and added to the tree. [method Node.get_tree] and [member current_scene] will be back to working as usual. + This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to [method Node.queue_free]. </description> </method> <method name="create_timer"> @@ -61,11 +67,11 @@ <param index="2" name="process_in_physics" type="bool" default="false" /> <param index="3" name="ignore_time_scale" type="bool" default="false" /> <description> - Returns a [SceneTreeTimer] which will emit [signal SceneTreeTimer.timeout] after the given time in seconds elapsed in this [SceneTree]. - If [param process_always] is set to [code]false[/code], pausing the [SceneTree] will also pause the timer. - If [param process_in_physics] is set to [code]true[/code], will update the [SceneTreeTimer] during the physics frame instead of the process frame (fixed framerate processing). - If [param ignore_time_scale] is set to [code]true[/code], will ignore [member Engine.time_scale] and update the [SceneTreeTimer] with the actual frame delta. - Commonly used to create a one-shot delay timer as in the following example: + Returns a new [SceneTreeTimer]. After [param time_sec] in seconds have passed, the timer will emit [signal SceneTreeTimer.timeout] and will be automatically freed. + If [param process_always] is [code]false[/code], the timer will be paused when setting [member SceneTree.paused] to [code]true[/code]. + If [param process_in_physics] is [code]true[/code], the timer will update at the end of the physics frame, instead of the process frame. + If [param ignore_time_scale] is [code]true[/code], the timer will ignore [member Engine.time_scale] and update with the real, elapsed time. + This method is commonly used to create a one-shot delay timer, as in the following example: [codeblocks] [gdscript] func some_function(): @@ -82,28 +88,27 @@ } [/csharp] [/codeblocks] - The timer will be automatically freed after its time elapses. - [b]Note:[/b] The timer is processed after all of the nodes in the current frame, i.e. node's [method Node._process] method would be called before the timer (or [method Node._physics_process] if [param process_in_physics] is set to [code]true[/code]). + [b]Note:[/b] The timer is always updated [i]after[/i] all of the nodes in the tree. A node's [method Node._process] method would be called before the timer updates (or [method Node._physics_process] if [param process_in_physics] is set to [code]true[/code]). </description> </method> <method name="create_tween"> <return type="Tween" /> <description> - Creates and returns a new [Tween]. The Tween will start automatically on the next process frame or physics frame (depending on [enum Tween.TweenProcessMode]). - [b]Note:[/b] When creating a [Tween] using this method, the [Tween] will not be tied to the [Node] that called it. It will continue to animate even if the [Node] is freed, but it will automatically finish if there's nothing left to animate. If you want the [Tween] to be automatically killed when the [Node] is freed, use [method Node.create_tween] or [method Tween.bind_node]. + Creates and returns a new [Tween] processed in this tree. The Tween will start automatically on the next process frame or physics frame (depending on its [enum Tween.TweenProcessMode]). + [b]Note:[/b] A [Tween] created using this method is not bound to any [Node]. It may keep working until there is nothing left to animate. If you want the [Tween] to be automatically killed when the [Node] is freed, use [method Node.create_tween] or [method Tween.bind_node]. </description> </method> <method name="get_first_node_in_group"> <return type="Node" /> <param index="0" name="group" type="StringName" /> <description> - Returns the first node in the specified group, or [code]null[/code] if the group is empty or does not exist. + Returns the first [Node] found inside the tree, that has been added to the given [param group], in scene hierarchy order. Returns [code]null[/code] if no match is found. See also [method get_nodes_in_group]. </description> </method> <method name="get_frame" qualifiers="const"> <return type="int" /> <description> - Returns the current frame number, i.e. the total frame count since the application started. + Returns how many frames have been processed, since the application started. This is [i]not[/i] a measurement of elapsed time. </description> </method> <method name="get_multiplayer" qualifiers="const"> @@ -116,28 +121,34 @@ <method name="get_node_count" qualifiers="const"> <return type="int" /> <description> - Returns the number of nodes in this [SceneTree]. + Returns the number of nodes inside this tree. + </description> + </method> + <method name="get_node_count_in_group" qualifiers="const"> + <return type="int" /> + <param index="0" name="group" type="StringName" /> + <description> + Returns the number of nodes assigned to the given group. </description> </method> <method name="get_nodes_in_group"> <return type="Node[]" /> <param index="0" name="group" type="StringName" /> <description> - Returns a list of all nodes assigned to the given group. + Returns an [Array] containing all nodes inside this tree, that have been added to the given [param group], in scene hierarchy order. </description> </method> <method name="get_processed_tweens"> <return type="Tween[]" /> <description> - Returns an array of currently existing [Tween]s in the [SceneTree] (both running and paused). + Returns an [Array] of currently existing [Tween]s in the tree, including paused tweens. </description> </method> <method name="has_group" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if the given group exists. - A group exists if any [Node] in the tree belongs to it (see [method Node.add_to_group]). Groups without nodes are removed automatically. + Returns [code]true[/code] if a node added to the given group [param name] exists in the tree. </description> </method> <method name="notify_group"> @@ -145,8 +156,8 @@ <param index="0" name="group" type="StringName" /> <param index="1" name="notification" type="int" /> <description> - Sends the given notification to all members of the [param group]. - [b]Note:[/b] [method notify_group] will immediately notify all members at once, which can cause stuttering if an expensive method is called as a result of sending the notification to lots of members. + Calls [method Object.notification] with the given [param notification] to all nodes inside this tree added to the [param group]. See also [method call_group] and [method set_group]. + [b]Note:[/b] This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations. </description> </method> <method name="notify_group_flags"> @@ -155,32 +166,30 @@ <param index="1" name="group" type="StringName" /> <param index="2" name="notification" type="int" /> <description> - Sends the given notification to all members of the [param group], respecting the given [enum GroupCallFlags]. - [b]Note:[/b] Group call flags are used to control the notification sending behavior. By default, notifications will be sent immediately in a way similar to [method notify_group]. However, if the [constant GROUP_CALL_DEFERRED] flag is present in the [param call_flags] argument, notifications will be sent at the end of the current frame in a way similar to using [code]Object.call_deferred("notification", ...)[/code]. + Calls [method Object.notification] with the given [param notification] to all nodes inside this tree added to the [param group]. Use [param call_flags] to customize this method's behavior (see [enum GroupCallFlags]). </description> </method> <method name="queue_delete"> <return type="void" /> <param index="0" name="obj" type="Object" /> <description> - Queues the given object for deletion, delaying the call to [method Object.free] to the end of the current frame. + Queues the given [param obj] to be deleted, calling its [method Object.free] at the end of the current frame. This method is similar to [method Node.queue_free]. </description> </method> <method name="quit"> <return type="void" /> <param index="0" name="exit_code" type="int" default="0" /> <description> - Quits the application at the end of the current iteration. Argument [param exit_code] can optionally be given (defaulting to 0) to customize the exit status code. - By convention, an exit code of [code]0[/code] indicates success whereas a non-zero exit code indicates an error. - For portability reasons, the exit code should be set between 0 and 125 (inclusive). - [b]Note:[/b] On iOS this method doesn't work. Instead, as recommended by the iOS Human Interface Guidelines, the user is expected to close apps via the Home button. + Quits the application at the end of the current iteration, with the given [param exit_code]. + By convention, an exit code of [code]0[/code] indicates success, whereas any other exit code indicates an error. For portability reasons, it should be between [code]0[/code] and [code]125[/code] (inclusive). + [b]Note:[/b] On iOS this method doesn't work. Instead, as recommended by the [url=https://developer.apple.com/library/archive/qa/qa1561/_index.html]iOS Human Interface Guidelines[/url], the user is expected to close apps via the Home button. </description> </method> <method name="reload_current_scene"> <return type="int" enum="Error" /> <description> - Reloads the currently active scene. - Returns [constant OK] on success, [constant ERR_UNCONFIGURED] if no [member current_scene] was defined yet, [constant ERR_CANT_OPEN] if [member current_scene] cannot be loaded into a [PackedScene], or [constant ERR_CANT_CREATE] if the scene cannot be instantiated. + Reloads the currently active scene, replacing [member current_scene] with a new instance of its original [PackedScene]. + Returns [constant OK] on success, [constant ERR_UNCONFIGURED] if no [member current_scene] is defined, [constant ERR_CANT_OPEN] if [member current_scene] cannot be loaded into a [PackedScene], or [constant ERR_CANT_CREATE] if the scene cannot be instantiated. </description> </method> <method name="set_group"> @@ -189,8 +198,9 @@ <param index="1" name="property" type="String" /> <param index="2" name="value" type="Variant" /> <description> - Sets the given [param property] to [param value] on all members of the given group. - [b]Note:[/b] [method set_group] will set the property immediately on all members at once, which can cause stuttering if a property with an expensive setter is set on lots of members. + Sets the given [param property] to [param value] on all nodes inside this tree added to the given [param group]. Nodes that do not have the [param property] are ignored. See also [method call_group] and [method notify_group]. + [b]Note:[/b] This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations. + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="set_group_flags"> @@ -200,8 +210,8 @@ <param index="2" name="property" type="String" /> <param index="3" name="value" type="Variant" /> <description> - Sets the given [param property] to [param value] on all members of the given group, respecting the given [enum GroupCallFlags]. - [b]Note:[/b] Group call flags are used to control the property setting behavior. By default, properties will be set immediately in a way similar to [method set_group]. However, if the [constant GROUP_CALL_DEFERRED] flag is present in the [param call_flags] argument, properties will be set at the end of the frame in a way similar to [method Object.call_deferred]. + Sets the given [param property] to [param value] on all nodes inside this tree added to the given [param group]. Nodes that do not have the [param property] are ignored. Use [param call_flags] to customize this method's behavior (see [enum GroupCallFlags]). + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="set_multiplayer"> @@ -226,8 +236,8 @@ For mobile platforms, see [member quit_on_go_back]. </member> <member name="current_scene" type="Node" setter="set_current_scene" getter="get_current_scene"> - Returns the root node of the currently running scene, regardless of its structure. - [b]Warning:[/b] Setting this directly might not work as expected, and will [i]not[/i] add or remove any nodes from the tree, consider using [method change_scene_to_file] or [method change_scene_to_packed] instead. + The root node of the currently loaded main scene, usually as a direct child of [member root]. See also [method change_scene_to_file], [method change_scene_to_packed], and [method reload_current_scene]. + [b]Warning:[/b] Setting this property directly may not work as expected, as it does [i]not[/i] add or remove any nodes from this tree. </member> <member name="debug_collisions_hint" type="bool" setter="set_debug_collisions_hint" getter="is_debugging_collisions_hint" default="false"> If [code]true[/code], collision shapes will be visible when running the game from the editor for debugging purposes. @@ -242,84 +252,90 @@ [b]Note:[/b] This property is not designed to be changed at run-time. Changing the value of [member debug_paths_hint] while the project is running will not have the desired effect. </member> <member name="edited_scene_root" type="Node" setter="set_edited_scene_root" getter="get_edited_scene_root"> - The root of the edited scene. + The root of the scene currently being edited in the editor. This is usually a direct child of [member root]. + [b]Note:[/b] This property does nothing in release builds. </member> <member name="multiplayer_poll" type="bool" setter="set_multiplayer_poll_enabled" getter="is_multiplayer_poll_enabled" default="true"> If [code]true[/code] (default value), enables automatic polling of the [MultiplayerAPI] for this SceneTree during [signal process_frame]. If [code]false[/code], you need to manually call [method MultiplayerAPI.poll] to process network packets and deliver RPCs. This allows running RPCs in a different loop (e.g. physics, thread, specific time step) and for manual [Mutex] protection when accessing the [MultiplayerAPI] from threads. </member> <member name="paused" type="bool" setter="set_pause" getter="is_paused" default="false"> - If [code]true[/code], the [SceneTree] is paused. Doing so will have the following behavior: - - 2D and 3D physics will be stopped. This includes signals and collision detection. - - [method Node._process], [method Node._physics_process] and [method Node._input] will not be called anymore in nodes. + If [code]true[/code], the scene tree is considered paused. This causes the following behavior: + - 2D and 3D physics will be stopped, as well as collision detection and related signals. + - Depending on each node's [member Node.process_mode], their [method Node._process], [method Node._physics_process] and [method Node._input] callback methods may not called anymore. + </member> + <member name="physics_interpolation" type="bool" setter="set_physics_interpolation_enabled" getter="is_physics_interpolation_enabled" default="false"> + If [code]true[/code], the renderer will interpolate the transforms of physics objects between the last two transforms, so that smooth motion is seen even when physics ticks do not coincide with rendered frames. + The default value of this property is controlled by [member ProjectSettings.physics/common/physics_interpolation]. </member> <member name="quit_on_go_back" type="bool" setter="set_quit_on_go_back" getter="is_quit_on_go_back" default="true"> If [code]true[/code], the application quits automatically when navigating back (e.g. using the system "Back" button on Android). To handle 'Go Back' button when this option is disabled, use [constant DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST]. </member> <member name="root" type="Window" setter="" getter="get_root"> - The [SceneTree]'s root [Window]. + The tree's root [Window]. This is top-most [Node] of the scene tree, and is always present. An absolute [NodePath] always starts from this node. Children of the root node may include the loaded [member current_scene], as well as any [url=$DOCS_URL/tutorials/scripting/singletons_autoload.html]AutoLoad[/url] configured in the Project Settings. + [b]Warning:[/b] Do not delete this node. This will result in unstable behavior, followed by a crash. </member> </members> <signals> <signal name="node_added"> <param index="0" name="node" type="Node" /> <description> - Emitted whenever a node is added to the [SceneTree]. + Emitted when the [param node] enters this tree. </description> </signal> <signal name="node_configuration_warning_changed"> <param index="0" name="node" type="Node" /> <description> - Emitted when a node's configuration changed. Only emitted in [code]tool[/code] mode. + Emitted when the [param node]'s [method Node.update_configuration_warnings] is called. Only emitted in the editor. </description> </signal> <signal name="node_removed"> <param index="0" name="node" type="Node" /> <description> - Emitted whenever a node is removed from the [SceneTree]. + Emitted when the [param node] exits this tree. </description> </signal> <signal name="node_renamed"> <param index="0" name="node" type="Node" /> <description> - Emitted whenever a node is renamed. + Emitted when the [param node]'s [member Node.name] is changed. </description> </signal> <signal name="physics_frame"> <description> - Emitted immediately before [method Node._physics_process] is called on every node in the [SceneTree]. + Emitted immediately before [method Node._physics_process] is called on every node in this tree. </description> </signal> <signal name="process_frame"> <description> - Emitted immediately before [method Node._process] is called on every node in the [SceneTree]. + Emitted immediately before [method Node._process] is called on every node in this tree. </description> </signal> <signal name="tree_changed"> <description> - Emitted whenever the [SceneTree] hierarchy changed (children being moved or renamed, etc.). + Emitted any time the tree's hierarchy changes (nodes being moved, renamed, etc.). </description> </signal> <signal name="tree_process_mode_changed"> <description> - This signal is only emitted in the editor, it allows the editor to update the visibility of disabled nodes. Emitted whenever any node's [member Node.process_mode] is changed. + Emitted when the [member Node.process_mode] of any node inside the tree is changed. Only emitted in the editor, to update the visibility of disabled nodes. </description> </signal> </signals> <constants> <constant name="GROUP_CALL_DEFAULT" value="0" enum="GroupCallFlags"> - Call a group with no flags (default). + Call nodes within a group with no special behavior (default). </constant> <constant name="GROUP_CALL_REVERSE" value="1" enum="GroupCallFlags"> - Call a group in reverse scene order. + Call nodes within a group in reverse tree hierarchy order (all nested children are called before their respective parent nodes). </constant> <constant name="GROUP_CALL_DEFERRED" value="2" enum="GroupCallFlags"> - Call a group at the end of the current frame (process or physics). + Call nodes within a group at the end of the current frame (can be either process or physics frame), similar to [method Object.call_deferred]. </constant> <constant name="GROUP_CALL_UNIQUE" value="4" enum="GroupCallFlags"> - Call a group only once even if the call is executed many times. - [b]Note:[/b] Arguments are not taken into account when deciding whether the call is unique or not. Therefore when the same method is called with different arguments, only the first call will be performed. + Call nodes within a group only once, even if the call is executed many times in the same frame. Must be combined with [constant GROUP_CALL_DEFERRED] to work. + [b]Note:[/b] Different arguments are not taken into account. Therefore, when the same call is executed with different arguments, only the first call will be performed. </constant> </constants> </class> diff --git a/doc/classes/Script.xml b/doc/classes/Script.xml index 28d763585d..fa8e4ef5f2 100644 --- a/doc/classes/Script.xml +++ b/doc/classes/Script.xml @@ -24,6 +24,27 @@ Returns the script directly inherited by this script. </description> </method> + <method name="get_global_name" qualifiers="const"> + <return type="StringName" /> + <description> + Returns the class name associated with the script, if there is one. Returns an empty string otherwise. + To give the script a global name, you can use the [code]class_name[/code] keyword in GDScript and the [code][GlobalClass][/code] attribute in C#. + [codeblocks] + [gdscript] + class_name MyNode + extends Node + [/gdscript] + [csharp] + using Godot; + + [GlobalClass] + public partial class MyNode : Node + { + } + [/csharp] + [/codeblocks] + </description> + </method> <method name="get_instance_base_type" qualifiers="const"> <return type="StringName" /> <description> diff --git a/doc/classes/ScriptExtension.xml b/doc/classes/ScriptExtension.xml index 51958a2a2a..d102676035 100644 --- a/doc/classes/ScriptExtension.xml +++ b/doc/classes/ScriptExtension.xml @@ -80,6 +80,13 @@ <description> </description> </method> + <method name="_get_script_method_argument_count" qualifiers="virtual const"> + <return type="Variant" /> + <param index="0" name="method" type="StringName" /> + <description> + Return the expected argument count for the given [param method], or [code]null[/code] if it can't be determined (which will then fall back to the default behavior). + </description> + </method> <method name="_get_script_method_list" qualifiers="virtual const"> <return type="Dictionary[]" /> <description> diff --git a/doc/classes/ScriptLanguage.xml b/doc/classes/ScriptLanguage.xml index 51134012c7..0a1b801f9b 100644 --- a/doc/classes/ScriptLanguage.xml +++ b/doc/classes/ScriptLanguage.xml @@ -6,4 +6,14 @@ </description> <tutorials> </tutorials> + <constants> + <constant name="SCRIPT_NAME_CASING_AUTO" value="0" enum="ScriptNameCasing"> + </constant> + <constant name="SCRIPT_NAME_CASING_PASCAL_CASE" value="1" enum="ScriptNameCasing"> + </constant> + <constant name="SCRIPT_NAME_CASING_SNAKE_CASE" value="2" enum="ScriptNameCasing"> + </constant> + <constant name="SCRIPT_NAME_CASING_KEBAB_CASE" value="3" enum="ScriptNameCasing"> + </constant> + </constants> </class> diff --git a/doc/classes/ScriptLanguageExtension.xml b/doc/classes/ScriptLanguageExtension.xml index 1a61618b53..a453866e27 100644 --- a/doc/classes/ScriptLanguageExtension.xml +++ b/doc/classes/ScriptLanguageExtension.xml @@ -34,6 +34,11 @@ <description> </description> </method> + <method name="_can_make_function" qualifiers="virtual const"> + <return type="bool" /> + <description> + </description> + </method> <method name="_complete_code" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="code" type="String" /> @@ -114,9 +119,10 @@ </method> <method name="_find_function" qualifiers="virtual const"> <return type="int" /> - <param index="0" name="class_name" type="String" /> - <param index="1" name="function_name" type="String" /> + <param index="0" name="function" type="String" /> + <param index="1" name="code" type="String" /> <description> + Returns the line where the function is defined in the code, or [code]-1[/code] if the function is not present. </description> </method> <method name="_finish" qualifiers="virtual"> @@ -202,10 +208,9 @@ <description> </description> </method> - <method name="_has_named_classes" qualifiers="virtual const" is_deprecated="true"> + <method name="_has_named_classes" qualifiers="virtual const" deprecated="This method is not called by the engine."> <return type="bool" /> <description> - [i]Deprecated.[/i] This method is not called by the engine. </description> </method> <method name="_init" qualifiers="virtual"> @@ -262,6 +267,11 @@ <description> </description> </method> + <method name="_preferred_file_name_casing" qualifiers="virtual const"> + <return type="int" enum="ScriptLanguage.ScriptNameCasing" /> + <description> + </description> + </method> <method name="_profiling_get_accumulated_data" qualifiers="virtual"> <return type="int" /> <param index="0" name="info_array" type="ScriptLanguageExtensionProfilingInfo*" /> @@ -276,6 +286,12 @@ <description> </description> </method> + <method name="_profiling_set_save_native_calls" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="enable" type="bool" /> + <description> + </description> + </method> <method name="_profiling_start" qualifiers="virtual"> <return type="void" /> <description> @@ -367,7 +383,7 @@ 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). </constant> <constant name="LOCATION_PARENT_MASK" value="256" enum="CodeCompletionLocation"> - 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. + 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. [code]0[/code] for the local class, [code]1[/code] for the parent, [code]2[/code] for the grandparent, etc.) to store the depth of an option in the class or a parent class. </constant> <constant name="LOCATION_OTHER_USER_CODE" value="512" enum="CodeCompletionLocation"> The option is from user code which is not local and not in a derived class (e.g. Autoload Singletons). diff --git a/doc/classes/ShapeCast3D.xml b/doc/classes/ShapeCast3D.xml index e189628f4c..ff057e8c70 100644 --- a/doc/classes/ShapeCast3D.xml +++ b/doc/classes/ShapeCast3D.xml @@ -119,11 +119,11 @@ Removes a collision exception so the shape does report collisions with the specified [RID]. </description> </method> - <method name="resource_changed" is_deprecated="true"> + <method name="resource_changed" deprecated="Use [signal Resource.changed] instead."> <return type="void" /> <param index="0" name="resource" type="Resource" /> <description> - [i]Obsoleted.[/i] Use [signal Resource.changed] instead. + This method does nothing. </description> </method> <method name="set_collision_mask_value"> diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml index bc3782d1a0..17c93af652 100644 --- a/doc/classes/Skeleton3D.xml +++ b/doc/classes/Skeleton3D.xml @@ -7,7 +7,6 @@ [Skeleton3D] provides an interface for managing a hierarchy of bones, including pose, rest and animation (see [Animation]). It can also use ragdoll physics. The overall transform of a bone with respect to the skeleton is determined by bone pose. Bone rest defines the initial transform of the bone pose. Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it is not the actual global/world transform of the bone. - To setup different types of inverse kinematics, consider using [SkeletonIK3D], or add a custom IK implementation in [method Node._process] as a child node. </description> <tutorials> <link title="3D Inverse Kinematics Demo">https://godotengine.org/asset-library/asset/523</link> @@ -15,10 +14,11 @@ </tutorials> <methods> <method name="add_bone"> - <return type="void" /> + <return type="int" /> <param index="0" name="name" type="String" /> <description> - Adds a bone, with name [param name]. [method get_bone_count] will become the bone index. + Adds a new bone with the given name. Returns the new bone's index, or [code]-1[/code] if this method fails. + [b]Note:[/b] Bone names should be unique, non empty, and cannot include the [code]:[/code] and [code]/[/code] characters. </description> </method> <method name="clear_bones"> @@ -27,7 +27,7 @@ Clear all the bones in this skeleton. </description> </method> - <method name="clear_bones_global_pose_override"> + <method name="clear_bones_global_pose_override" deprecated=""> <return type="void" /> <description> Removes the global pose override on all bones in the skeleton. @@ -45,11 +45,10 @@ Returns the bone index that matches [param name] as its name. </description> </method> - <method name="force_update_all_bone_transforms" is_deprecated="true"> + <method name="force_update_all_bone_transforms" deprecated="This method should only be called internally."> <return type="void" /> <description> Force updates the bone transforms/poses for all bones in the skeleton. - [i]Deprecated.[/i] Do not use. </description> </method> <method name="force_update_bone_child_transform"> @@ -59,11 +58,16 @@ Force updates the bone transform for the bone at [param bone_idx] and all of its children. </description> </method> + <method name="get_animate_physical_bones" qualifiers="const" deprecated=""> + <return type="bool" /> + <description> + </description> + </method> <method name="get_bone_children" qualifiers="const"> <return type="PackedInt32Array" /> <param index="0" name="bone_idx" type="int" /> <description> - Returns an array containing the bone indexes of all the children node of the passed in bone, [param bone_idx]. + Returns an array containing the bone indexes of all the child node of the passed in bone, [param bone_idx]. </description> </method> <method name="get_bone_count" qualifiers="const"> @@ -77,16 +81,17 @@ <param index="0" name="bone_idx" type="int" /> <description> Returns the overall transform of the specified bone, with respect to the skeleton. Being relative to the skeleton frame, this is not the actual "global" transform of the bone. + [b]Note:[/b] This is the global pose you set to the skeleton in the process, the final global pose can get overridden by modifiers in the deferred process, if you want to access the final global pose, use [signal SkeletonModifier3D.modification_processed]. </description> </method> - <method name="get_bone_global_pose_no_override" qualifiers="const"> + <method name="get_bone_global_pose_no_override" qualifiers="const" deprecated=""> <return type="Transform3D" /> <param index="0" name="bone_idx" type="int" /> <description> Returns the overall transform of the specified bone, with respect to the skeleton, but without any global pose overrides. Being relative to the skeleton frame, this is not the actual "global" transform of the bone. </description> </method> - <method name="get_bone_global_pose_override" qualifiers="const"> + <method name="get_bone_global_pose_override" qualifiers="const" deprecated=""> <return type="Transform3D" /> <param index="0" name="bone_idx" type="int" /> <description> @@ -120,6 +125,7 @@ <param index="0" name="bone_idx" type="int" /> <description> Returns the pose transform of the specified bone. + [b]Note:[/b] This is the pose you set to the skeleton in the process, the final pose can get overridden by modifiers in the deferred process, if you want to access the final pose, use [signal SkeletonModifier3D.modification_processed]. </description> </method> <method name="get_bone_pose_position" qualifiers="const"> @@ -177,7 +183,7 @@ Returns all bones in the skeleton to their rest poses. </description> </method> - <method name="physical_bones_add_collision_exception"> + <method name="physical_bones_add_collision_exception" deprecated=""> <return type="void" /> <param index="0" name="exception" type="RID" /> <description> @@ -185,7 +191,7 @@ Works just like the [RigidBody3D] node. </description> </method> - <method name="physical_bones_remove_collision_exception"> + <method name="physical_bones_remove_collision_exception" deprecated=""> <return type="void" /> <param index="0" name="exception" type="RID" /> <description> @@ -193,7 +199,7 @@ Works just like the [RigidBody3D] node. </description> </method> - <method name="physical_bones_start_simulation"> + <method name="physical_bones_start_simulation" deprecated=""> <return type="void" /> <param index="0" name="bones" type="StringName[]" default="[]" /> <description> @@ -201,7 +207,7 @@ Optionally, a list of bone names can be passed-in, allowing only the passed-in bones to be simulated. </description> </method> - <method name="physical_bones_stop_simulation"> + <method name="physical_bones_stop_simulation" deprecated=""> <return type="void" /> <description> Tells the [PhysicalBone3D] nodes in the Skeleton to stop simulating. @@ -227,6 +233,12 @@ Sets all bone poses to rests. </description> </method> + <method name="set_animate_physical_bones" deprecated=""> + <return type="void" /> + <param index="0" name="enabled" type="bool" /> + <description> + </description> + </method> <method name="set_bone_enabled"> <return type="void" /> <param index="0" name="bone_idx" type="int" /> @@ -235,7 +247,16 @@ Disables the pose for the bone at [param bone_idx] if [code]false[/code], enables the bone pose if [code]true[/code]. </description> </method> - <method name="set_bone_global_pose_override"> + <method name="set_bone_global_pose"> + <return type="void" /> + <param index="0" name="bone_idx" type="int" /> + <param index="1" name="pose" type="Transform3D" /> + <description> + Sets the global pose transform, [param pose], for the bone at [param bone_idx]. + [b]Note:[/b] If other bone poses have been changed, this method executes an update process and will cause performance to deteriorate. If you know that multiple global poses will be applied, consider using [method set_bone_pose] with precalculation. + </description> + </method> + <method name="set_bone_global_pose_override" deprecated=""> <return type="void" /> <param index="0" name="bone_idx" type="int" /> <param index="1" name="pose" type="Transform3D" /> @@ -252,6 +273,7 @@ <param index="0" name="bone_idx" type="int" /> <param index="1" name="name" type="String" /> <description> + Sets the bone name, [param name], for the bone at [param bone_idx]. </description> </method> <method name="set_bone_parent"> @@ -263,6 +285,14 @@ [b]Note:[/b] [param parent_idx] must be less than [param bone_idx]. </description> </method> + <method name="set_bone_pose"> + <return type="void" /> + <param index="0" name="bone_idx" type="int" /> + <param index="1" name="pose" type="Transform3D" /> + <description> + Sets the pose transform, [param pose], for the bone at [param bone_idx]. + </description> + </method> <method name="set_bone_pose_position"> <return type="void" /> <param index="0" name="bone_idx" type="int" /> @@ -304,38 +334,55 @@ </method> </methods> <members> - <member name="animate_physical_bones" type="bool" setter="set_animate_physical_bones" getter="get_animate_physical_bones" default="true"> + <member name="modifier_callback_mode_process" type="int" setter="set_modifier_callback_mode_process" getter="get_modifier_callback_mode_process" enum="Skeleton3D.ModifierCallbackModeProcess" default="1"> + Sets the processing timing for the Modifier. </member> <member name="motion_scale" type="float" setter="set_motion_scale" getter="get_motion_scale" default="1.0"> Multiplies the 3D position track animation. [b]Note:[/b] Unless this value is [code]1.0[/code], the key value in animation will not match the actual position value. </member> <member name="show_rest_only" type="bool" setter="set_show_rest_only" getter="is_show_rest_only" default="false"> + If [code]true[/code], forces the bones in their default rest pose, regardless of their values. In the editor, this also prevents the bones from being edited. </member> </members> <signals> <signal name="bone_enabled_changed"> <param index="0" name="bone_idx" type="int" /> <description> + Emitted when the bone at [param bone_idx] is toggled with [method set_bone_enabled]. Use [method is_bone_enabled] to check the new value. + </description> + </signal> + <signal name="bone_list_changed"> + <description> </description> </signal> <signal name="bone_pose_changed"> <param index="0" name="bone_idx" type="int" /> <description> - This signal is emitted when one of the bones in the Skeleton3D node have changed their pose. This is used to inform nodes that rely on bone positions that one of the bones in the Skeleton3D have changed their transform/pose. + Emitted when the bone at [param bone_idx] changes its transform/pose. This can be used to update other nodes that rely on bone positions. </description> </signal> <signal name="pose_updated"> <description> + Emitted when the pose is updated, after [constant NOTIFICATION_UPDATE_SKELETON] is received. </description> </signal> <signal name="show_rest_only_changed"> <description> + Emitted when the value of [member show_rest_only] changes. </description> </signal> </signals> <constants> <constant name="NOTIFICATION_UPDATE_SKELETON" value="50"> + Notification received when this skeleton's pose needs to be updated. + This notification is received [i]before[/i] the related [signal pose_updated] signal. + </constant> + <constant name="MODIFIER_CALLBACK_MODE_PROCESS_PHYSICS" value="0" enum="ModifierCallbackModeProcess"> + Set a flag to process modification during physics frames (see [constant Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS]). + </constant> + <constant name="MODIFIER_CALLBACK_MODE_PROCESS_IDLE" value="1" enum="ModifierCallbackModeProcess"> + Set a flag to process modification during process frames (see [constant Node.NOTIFICATION_INTERNAL_PROCESS]). </constant> </constants> </class> diff --git a/doc/classes/SkeletonIK3D.xml b/doc/classes/SkeletonIK3D.xml index c72383c84f..46b3d79795 100644 --- a/doc/classes/SkeletonIK3D.xml +++ b/doc/classes/SkeletonIK3D.xml @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonIK3D" inherits="Node" is_deprecated="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonIK3D" inherits="SkeletonModifier3D" deprecated="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A node used to rotate all bones of a [Skeleton3D] bone chain a way that places the end bone at a desired 3D position. </brief_description> <description> - SkeletonIK3D is used to rotate all bones of a [Skeleton3D] bone chain a way that places the end bone at a desired 3D position. A typical scenario for IK in games is to place a character's feet on the ground or a character's hands on a currently held object. SkeletonIK uses FabrikInverseKinematic internally to solve the bone chain and applies the results to the [Skeleton3D] [code]bones_global_pose_override[/code] property for all affected bones in the chain. If fully applied, this overwrites any bone transform from [Animation]s or bone custom poses set by users. The applied amount can be controlled with the [member interpolation] property. + SkeletonIK3D is used to rotate all bones of a [Skeleton3D] bone chain a way that places the end bone at a desired 3D position. A typical scenario for IK in games is to place a character's feet on the ground or a character's hands on a currently held object. SkeletonIK uses FabrikInverseKinematic internally to solve the bone chain and applies the results to the [Skeleton3D] [code]bones_global_pose_override[/code] property for all affected bones in the chain. If fully applied, this overwrites any bone transform from [Animation]s or bone custom poses set by users. The applied amount can be controlled with the [member SkeletonModifier3D.influence] property. [codeblock] # Apply IK effect automatically on every new frame (not the current) skeleton_ik_node.start() @@ -16,15 +16,14 @@ skeleton_ik_node.stop() # Apply full IK effect - skeleton_ik_node.set_interpolation(1.0) + skeleton_ik_node.set_influence(1.0) # Apply half IK effect - skeleton_ik_node.set_interpolation(0.5) + skeleton_ik_node.set_influence(0.5) # Apply zero IK effect (a value at or below 0.01 also removes bones_global_pose_override on Skeleton) - skeleton_ik_node.set_interpolation(0.0) + skeleton_ik_node.set_influence(0.0) [/codeblock] - [i]Deprecated.[/i] This class is deprecated, and might be removed in a future release. </description> <tutorials> <link title="3D Inverse Kinematics Demo">https://godotengine.org/asset-library/asset/523</link> @@ -57,9 +56,6 @@ </method> </methods> <members> - <member name="interpolation" type="float" setter="set_interpolation" getter="get_interpolation" default="1.0"> - Interpolation value for how much the IK results are applied to the current skeleton bone chain. A value of [code]1.0[/code] will overwrite all skeleton bone transforms completely while a value of [code]0.0[/code] will visually disable the SkeletonIK. A value at or below [code]0.01[/code] also calls [method Skeleton3D.clear_bones_global_pose_override]. - </member> <member name="magnet" type="Vector3" setter="set_magnet_position" getter="get_magnet_position" default="Vector3(0, 0, 0)"> Secondary target position (first is [member target] property or [member target_node]) for the IK chain. Use magnet position (pole target) to control the bending of the IK chain. Only works if the bone chain has more than 2 bones. The middle chain bone position will be linearly interpolated with the magnet position. </member> diff --git a/doc/classes/SkeletonModification2D.xml b/doc/classes/SkeletonModification2D.xml index c1eee9cb5c..c09e63be85 100644 --- a/doc/classes/SkeletonModification2D.xml +++ b/doc/classes/SkeletonModification2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2D" inherits="Resource" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2D" inherits="Resource" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Base class for resources that operate on [Bone2D]s in a [Skeleton2D]. </brief_description> diff --git a/doc/classes/SkeletonModification2DCCDIK.xml b/doc/classes/SkeletonModification2DCCDIK.xml index af71ae809c..e20cbd8960 100644 --- a/doc/classes/SkeletonModification2DCCDIK.xml +++ b/doc/classes/SkeletonModification2DCCDIK.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2DCCDIK" inherits="SkeletonModification2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2DCCDIK" inherits="SkeletonModification2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A modification that uses CCDIK to manipulate a series of bones to reach a target in 2D. </brief_description> diff --git a/doc/classes/SkeletonModification2DFABRIK.xml b/doc/classes/SkeletonModification2DFABRIK.xml index a31c908082..16784dbf4d 100644 --- a/doc/classes/SkeletonModification2DFABRIK.xml +++ b/doc/classes/SkeletonModification2DFABRIK.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2DFABRIK" inherits="SkeletonModification2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2DFABRIK" inherits="SkeletonModification2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A modification that uses FABRIK to manipulate a series of [Bone2D] nodes to reach a target. </brief_description> diff --git a/doc/classes/SkeletonModification2DJiggle.xml b/doc/classes/SkeletonModification2DJiggle.xml index 7683d29d1c..4a09806b82 100644 --- a/doc/classes/SkeletonModification2DJiggle.xml +++ b/doc/classes/SkeletonModification2DJiggle.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2DJiggle" inherits="SkeletonModification2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2DJiggle" inherits="SkeletonModification2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A modification that jiggles [Bone2D] nodes as they move towards a target. </brief_description> diff --git a/doc/classes/SkeletonModification2DLookAt.xml b/doc/classes/SkeletonModification2DLookAt.xml index 797722eb86..232104f6ac 100644 --- a/doc/classes/SkeletonModification2DLookAt.xml +++ b/doc/classes/SkeletonModification2DLookAt.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2DLookAt" inherits="SkeletonModification2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2DLookAt" inherits="SkeletonModification2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A modification that rotates a [Bone2D] node to look at a target. </brief_description> diff --git a/doc/classes/SkeletonModification2DPhysicalBones.xml b/doc/classes/SkeletonModification2DPhysicalBones.xml index 930f201ad5..af9e982f6a 100644 --- a/doc/classes/SkeletonModification2DPhysicalBones.xml +++ b/doc/classes/SkeletonModification2DPhysicalBones.xml @@ -1,11 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2DPhysicalBones" inherits="SkeletonModification2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2DPhysicalBones" inherits="SkeletonModification2D" experimental="Physical bones may be changed in the future to perform the position update of [Bone2D] on their own, without needing this resource." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A modification that applies the transforms of [PhysicalBone2D] nodes to [Bone2D] nodes. </brief_description> <description> This modification takes the transforms of [PhysicalBone2D] nodes and applies them to [Bone2D] nodes. This allows the [Bone2D] nodes to react to physics thanks to the linked [PhysicalBone2D] nodes. - Experimental. Physical bones may be changed in the future to perform the position update of [Bone2D] on their own. </description> <tutorials> </tutorials> diff --git a/doc/classes/SkeletonModification2DStackHolder.xml b/doc/classes/SkeletonModification2DStackHolder.xml index 60fba86d32..5b9f6f270a 100644 --- a/doc/classes/SkeletonModification2DStackHolder.xml +++ b/doc/classes/SkeletonModification2DStackHolder.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2DStackHolder" inherits="SkeletonModification2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2DStackHolder" inherits="SkeletonModification2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A modification that holds and executes a [SkeletonModificationStack2D]. </brief_description> diff --git a/doc/classes/SkeletonModification2DTwoBoneIK.xml b/doc/classes/SkeletonModification2DTwoBoneIK.xml index 2206aa5719..1c7bb32f4a 100644 --- a/doc/classes/SkeletonModification2DTwoBoneIK.xml +++ b/doc/classes/SkeletonModification2DTwoBoneIK.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModification2DTwoBoneIK" inherits="SkeletonModification2D" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModification2DTwoBoneIK" inherits="SkeletonModification2D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A modification that rotates two bones using the law of cosines to reach the target. </brief_description> diff --git a/doc/classes/SkeletonModificationStack2D.xml b/doc/classes/SkeletonModificationStack2D.xml index 391771d1d3..a006f727ee 100644 --- a/doc/classes/SkeletonModificationStack2D.xml +++ b/doc/classes/SkeletonModificationStack2D.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SkeletonModificationStack2D" inherits="Resource" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SkeletonModificationStack2D" inherits="Resource" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A resource that holds a stack of [SkeletonModification2D]s. </brief_description> diff --git a/doc/classes/SkeletonModifier3D.xml b/doc/classes/SkeletonModifier3D.xml new file mode 100644 index 0000000000..fab33750ea --- /dev/null +++ b/doc/classes/SkeletonModifier3D.xml @@ -0,0 +1,29 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="SkeletonModifier3D" inherits="Node3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A Node that may modify Skeleton3D's bone. + </brief_description> + <description> + [SkeletonModifier3D] retrieves a target [Skeleton3D] by having a [Skeleton3D] parent. + If there is [AnimationMixer], modification always performs after playback process of the [AnimationMixer]. + </description> + <tutorials> + </tutorials> + <members> + <member name="active" type="bool" setter="set_active" getter="is_active" default="true"> + If [code]true[/code], the [SkeletonModifier3D] will be processing. + </member> + <member name="influence" type="float" setter="set_influence" getter="get_influence" default="1.0"> + Sets the influence of the modification. + [b]Note:[/b] This value is used by [Skeleton3D] to blend, so the [SkeletonModifier3D] should always apply only 100% of the result without interpolation. + </member> + </members> + <signals> + <signal name="modification_processed"> + <description> + Notifies when the modification have been finished. + [b]Note:[/b] If you want to get the modified bone pose by the modifier, you must use [method Skeleton3D.get_bone_pose] or [method Skeleton3D.get_bone_global_pose] at the moment this signal is fired. + </description> + </signal> + </signals> +</class> diff --git a/doc/classes/SkeletonProfile.xml b/doc/classes/SkeletonProfile.xml index 3ed29668e4..b5bb4e3639 100644 --- a/doc/classes/SkeletonProfile.xml +++ b/doc/classes/SkeletonProfile.xml @@ -83,6 +83,14 @@ Returns the texture of the group at [param group_idx] that will be the drawing group background image in the [BoneMap] editor. </description> </method> + <method name="is_required" qualifiers="const"> + <return type="bool" /> + <param index="0" name="bone_idx" type="int" /> + <description> + Returns whether the bone at [param bone_idx] is required for retargeting. + This value is used by the bone map editor. If this method returns [code]true[/code], and no bone is assigned, the handle color will be red on the bone map editor. + </description> + </method> <method name="set_bone_name"> <return type="void" /> <param index="0" name="bone_idx" type="int" /> @@ -141,6 +149,14 @@ Sets the reference pose transform for bone [param bone_idx]. </description> </method> + <method name="set_required"> + <return type="void" /> + <param index="0" name="bone_idx" type="int" /> + <param index="1" name="required" type="bool" /> + <description> + Sets the required status for bone [param bone_idx] to [param required]. + </description> + </method> <method name="set_tail_direction"> <return type="void" /> <param index="0" name="bone_idx" type="int" /> diff --git a/doc/classes/SkeletonProfileHumanoid.xml b/doc/classes/SkeletonProfileHumanoid.xml index fe9eded7a9..5539d1d980 100644 --- a/doc/classes/SkeletonProfileHumanoid.xml +++ b/doc/classes/SkeletonProfileHumanoid.xml @@ -5,6 +5,63 @@ </brief_description> <description> A [SkeletonProfile] as a preset that is optimized for the human form. This exists for standardization, so all parameters are read-only. + A humanoid skeleton profile contains 54 bones divided in 4 groups: [code]"Body"[/code], [code]"Face"[/code], [code]"LeftHand"[/code], and [code]"RightHand"[/code]. It is structured as follows: + [codeblock] + Root + └─ Hips + ├─ LeftUpperLeg + │ └─ LeftLowerLeg + │ └─ LeftFoot + │ └─ LeftToes + ├─ RightUpperLeg + │ └─ RightLowerLeg + │ └─ RightFoot + │ └─ RightToes + └─ Spine + └─ Chest + └─ UpperChest + ├─ Neck + │ └─ Head + │ ├─ Jaw + │ ├─ LeftEye + │ └─ RightEye + ├─ LeftShoulder + │ └─ LeftUpperArm + │ └─ LeftLowerArm + │ └─ LeftHand + │ ├─ LeftThumbMetacarpal + │ │ └─ LeftThumbProximal + │ ├─ LeftIndexProximal + │ │ └─ LeftIndexIntermediate + │ │ └─ LeftIndexDistal + │ ├─ LeftMiddleProximal + │ │ └─ LeftMiddleIntermediate + │ │ └─ LeftMiddleDistal + │ ├─ LeftRingProximal + │ │ └─ LeftRingIntermediate + │ │ └─ LeftRingDistal + │ └─ LeftLittleProximal + │ └─ LeftLittleIntermediate + │ └─ LeftLittleDistal + └─ RightShoulder + └─ RightUpperArm + └─ RightLowerArm + └─ RightHand + ├─ RightThumbMetacarpal + │ └─ RightThumbProximal + ├─ RightIndexProximal + │ └─ RightIndexIntermediate + │ └─ RightIndexDistal + ├─ RightMiddleProximal + │ └─ RightMiddleIntermediate + │ └─ RightMiddleDistal + ├─ RightRingProximal + │ └─ RightRingIntermediate + │ └─ RightRingDistal + └─ RightLittleProximal + └─ RightLittleIntermediate + └─ RightLittleDistal + [/codeblock] </description> <tutorials> <link title="Retargeting 3D Skeletons">$DOCS_URL/tutorials/assets_pipeline/retargeting_3d_skeletons.html</link> diff --git a/doc/classes/Slider.xml b/doc/classes/Slider.xml index 0471b8c275..a4ffa5c1e7 100644 --- a/doc/classes/Slider.xml +++ b/doc/classes/Slider.xml @@ -9,7 +9,7 @@ <tutorials> </tutorials> <members> - <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true"> + <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true" keywords="readonly, disabled, enabled"> If [code]true[/code], the slider can be interacted with. If [code]false[/code], the value can be changed only by code. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> @@ -33,7 +33,7 @@ </signal> <signal name="drag_started"> <description> - Emitted when dragging is started. + Emitted when dragging is started. This is emitted before the corresponding [signal Range.value_changed] signal. </description> </signal> </signals> diff --git a/doc/classes/SoftBody3D.xml b/doc/classes/SoftBody3D.xml index b5202bd4e3..a4d80a7c3e 100644 --- a/doc/classes/SoftBody3D.xml +++ b/doc/classes/SoftBody3D.xml @@ -41,6 +41,7 @@ <method name="get_physics_rid" qualifiers="const"> <return type="RID" /> <description> + Returns the internal [RID] used by the [PhysicsServer3D] for this body. </description> </method> <method name="get_point_transform"> @@ -100,11 +101,14 @@ [b]Note:[/b] Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See [url=$DOCS_URL/tutorials/physics/physics_introduction.html#collision-layers-and-masks]Collision layers and masks[/url] in the documentation for more information. </member> <member name="damping_coefficient" type="float" setter="set_damping_coefficient" getter="get_damping_coefficient" default="0.01"> + The body's damping coefficient. Higher values will slow down the body more noticeably when forces are applied. </member> <member name="disable_mode" type="int" setter="set_disable_mode" getter="get_disable_mode" enum="SoftBody3D.DisableMode" default="0"> Defines the behavior in physics when [member Node.process_mode] is set to [constant Node.PROCESS_MODE_DISABLED]. See [enum DisableMode] for more details about the different modes. </member> <member name="drag_coefficient" type="float" setter="set_drag_coefficient" getter="get_drag_coefficient" default="0.0"> + The body's drag coefficient. Higher values increase this body's air resistance. + [b]Note:[/b] This value is currently unused by Godot's default physics implementation. </member> <member name="linear_stiffness" type="float" setter="set_linear_stiffness" getter="get_linear_stiffness" default="0.5"> Higher values will result in a stiffer body, while lower values will increase the body's ability to bend. The value can be between [code]0.0[/code] and [code]1.0[/code] (inclusive). @@ -113,6 +117,7 @@ [NodePath] to a [CollisionObject3D] this SoftBody3D should avoid clipping. </member> <member name="pressure_coefficient" type="float" setter="set_pressure_coefficient" getter="get_pressure_coefficient" default="0.0"> + The pressure coefficient of this soft body. Simulate pressure build-up from inside this body. Higher values increase the strength of this effect. </member> <member name="ray_pickable" type="bool" setter="set_ray_pickable" getter="is_ray_pickable" default="true"> If [code]true[/code], the [SoftBody3D] will respond to [RayCast3D]s. diff --git a/doc/classes/SpinBox.xml b/doc/classes/SpinBox.xml index 8627a9e40f..03e247ec8a 100644 --- a/doc/classes/SpinBox.xml +++ b/doc/classes/SpinBox.xml @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="SpinBox" inherits="Range" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="SpinBox" inherits="Range" keywords="number, numeric, input" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> An input field for numbers. </brief_description> <description> - [SpinBox] is a numerical input text field. It allows entering integers and floating point numbers. + [SpinBox] is a numerical input text field. It allows entering integers and floating-point numbers. [b]Example:[/b] [codeblocks] [gdscript] @@ -52,7 +52,7 @@ <member name="custom_arrow_step" type="float" setter="set_custom_arrow_step" getter="get_custom_arrow_step" default="0.0"> If not [code]0[/code], [member Range.value] will always be rounded to a multiple of [member custom_arrow_step] when interacting with the arrow buttons of the [SpinBox]. </member> - <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true"> + <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true" keywords="readonly, disabled, enabled"> If [code]true[/code], the [SpinBox] will be editable. Otherwise, it will be read only. </member> <member name="prefix" type="String" setter="set_prefix" getter="get_prefix" default=""""> diff --git a/doc/classes/SpotLight3D.xml b/doc/classes/SpotLight3D.xml index e89c99db1c..ba70edb933 100644 --- a/doc/classes/SpotLight3D.xml +++ b/doc/classes/SpotLight3D.xml @@ -24,8 +24,10 @@ The spotlight's [i]angular[/i] attenuation curve. See also [member spot_attenuation]. </member> <member name="spot_attenuation" type="float" setter="set_param" getter="get_param" default="1.0"> - The spotlight's light energy (drop-off) attenuation curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. Zero and negative values are allowed but can produce unusual effects. See also [member spot_angle_attenuation]. - [b]Note:[/b] Very high [member spot_attenuation] values (typically above 10) can impact performance negatively if the light is made to use a larger [member spot_range] to compensate. This is because culling opportunities will become less common and shading costs will be increased (as the light will cover more pixels on screen while resulting in the same amount of brightness). To improve performance, use the lowest [member spot_attenuation] value possible for the visuals you're trying to achieve. + Controls the distance attenuation function for spotlights. + A value of [code]0.0[/code] smoothly attenuates light at the edge of the range. A value of [code]1.0[/code] approaches a physical lighting model. A value of [code]0.5[/code] approximates linear attenuation. + [b]Note:[/b] Setting it to [code]1.0[/code] may result in distant objects receiving minimal light, even within range. For example, with a range of [code]4096[/code], an object at [code]100[/code] units receives less than [code]0.1[/code] energy. + [b]Note:[/b] Using negative or values higher than [code]10.0[/code] may lead to unexpected results. </member> <member name="spot_range" type="float" setter="set_param" getter="get_param" default="5.0"> The maximal range that can be reached by the spotlight. Note that the effectively lit area may appear to be smaller depending on the [member spot_attenuation] in use. No matter the [member spot_attenuation] in use, the light will never reach anything outside this range. diff --git a/doc/classes/Sprite2D.xml b/doc/classes/Sprite2D.xml index 8eb9e26a83..8dcf286b3a 100644 --- a/doc/classes/Sprite2D.xml +++ b/doc/classes/Sprite2D.xml @@ -44,7 +44,7 @@ <return type="bool" /> <param index="0" name="pos" type="Vector2" /> <description> - Returns [code]true[/code], if the pixel at the given position is opaque and [code]false[/code] in other case. + Returns [code]true[/code], if the pixel at the given position is opaque and [code]false[/code] in other case. The position is in local coordinates. [b]Note:[/b] It also returns [code]false[/code], if the sprite's texture is [code]null[/code] or if the given position is invalid. </description> </method> @@ -52,6 +52,7 @@ <members> <member name="centered" type="bool" setter="set_centered" getter="is_centered" default="true"> If [code]true[/code], texture is centered. + [b]Note:[/b] For games with a pixel art aesthetic, textures may appear deformed when centered. This is caused by their position being between pixels. To prevent this, set this property to [code]false[/code], or consider enabling [member ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel] and [member ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel]. </member> <member name="flip_h" type="bool" setter="set_flip_h" getter="is_flipped_h" default="false"> If [code]true[/code], texture is flipped horizontally. @@ -60,13 +61,13 @@ If [code]true[/code], texture is flipped vertically. </member> <member name="frame" type="int" setter="set_frame" getter="get_frame" default="0"> - Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. + Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. This property is automatically adjusted when [member hframes] or [member vframes] are changed to keep pointing to the same visual frame (same column and row). If that's impossible, this value is reset to [code]0[/code]. </member> <member name="frame_coords" type="Vector2i" setter="set_frame_coords" getter="get_frame_coords" default="Vector2i(0, 0)"> Coordinates of the frame to display from sprite sheet. This is as an alias for the [member frame] property. [member hframes] or [member vframes] must be greater than 1. </member> <member name="hframes" type="int" setter="set_hframes" getter="get_hframes" default="1"> - The number of columns in the sprite sheet. + The number of columns in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> <member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)"> The texture's drawing offset. @@ -84,7 +85,7 @@ [Texture2D] object to draw. </member> <member name="vframes" type="int" setter="set_vframes" getter="get_vframes" default="1"> - The number of rows in the sprite sheet. + The number of rows in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> </members> <signals> diff --git a/doc/classes/Sprite3D.xml b/doc/classes/Sprite3D.xml index 9733c5f48a..4b4421aeba 100644 --- a/doc/classes/Sprite3D.xml +++ b/doc/classes/Sprite3D.xml @@ -10,13 +10,13 @@ </tutorials> <members> <member name="frame" type="int" setter="set_frame" getter="get_frame" default="0"> - Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. + Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. This property is automatically adjusted when [member hframes] or [member vframes] are changed to keep pointing to the same visual frame (same column and row). If that's impossible, this value is reset to [code]0[/code]. </member> <member name="frame_coords" type="Vector2i" setter="set_frame_coords" getter="get_frame_coords" default="Vector2i(0, 0)"> Coordinates of the frame to display from sprite sheet. This is as an alias for the [member frame] property. [member hframes] or [member vframes] must be greater than 1. </member> <member name="hframes" type="int" setter="set_hframes" getter="get_hframes" default="1"> - The number of columns in the sprite sheet. + The number of columns in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> <member name="region_enabled" type="bool" setter="set_region_enabled" getter="is_region_enabled" default="false"> If [code]true[/code], the sprite will use [member region_rect] and display only the specified part of its texture. @@ -28,7 +28,7 @@ [Texture2D] object to draw. If [member GeometryInstance3D.material_override] is used, this will be overridden. The size information is still used. </member> <member name="vframes" type="int" setter="set_vframes" getter="get_vframes" default="1"> - The number of rows in the sprite sheet. + The number of rows in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> </members> <signals> diff --git a/doc/classes/SpriteBase3D.xml b/doc/classes/SpriteBase3D.xml index a87608bb72..d6f8a519db 100644 --- a/doc/classes/SpriteBase3D.xml +++ b/doc/classes/SpriteBase3D.xml @@ -58,6 +58,7 @@ </member> <member name="billboard" type="int" setter="set_billboard_mode" getter="get_billboard_mode" enum="BaseMaterial3D.BillboardMode" default="0"> The billboard mode to use for the sprite. See [enum BaseMaterial3D.BillboardMode] for possible values. + [b]Note:[/b] When billboarding is enabled and the material also casts shadows, billboards will face [b]the[/b] camera in the scene when rendering shadows. In scenes with multiple cameras, the intended shadow cannot be determined and this will result in undefined behavior. See [url=https://github.com/godotengine/godot/pull/72638]GitHub Pull Request #72638[/url] for details. </member> <member name="centered" type="bool" setter="set_centered" getter="is_centered" default="true"> If [code]true[/code], texture will be centered. @@ -74,8 +75,9 @@ <member name="flip_v" type="bool" setter="set_flip_v" getter="is_flipped_v" default="false"> If [code]true[/code], texture is flipped vertically. </member> - <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)"> - A color value used to [i]multiply[/i] the texture's colors. Can be used for mood-coloring or to simulate the color of light. + <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)" keywords="color, colour"> + A color value used to [i]multiply[/i] the texture's colors. Can be used for mood-coloring or to simulate the color of ambient light. + [b]Note:[/b] Unlike [member CanvasItem.modulate] for 2D, colors with values above [code]1.0[/code] (overbright) are not supported. [b]Note:[/b] If a [member GeometryInstance3D.material_override] is defined on the [SpriteBase3D], the material override must be configured to take vertex colors into account for albedo. Otherwise, the color defined in [member modulate] will be ignored. For a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] must be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. </member> <member name="no_depth_test" type="bool" setter="set_draw_flag" getter="get_draw_flag" default="false"> @@ -97,6 +99,7 @@ </member> <member name="texture_filter" type="int" setter="set_texture_filter" getter="get_texture_filter" enum="BaseMaterial3D.TextureFilter" default="3"> Filter flags for the texture. See [enum BaseMaterial3D.TextureFilter] for options. + [b]Note:[/b] Linear filtering may cause artifacts around the edges, which are especially noticeable on opaque textures. To prevent this, use textures with transparent or identical colors around the edges. </member> <member name="transparent" type="bool" setter="set_draw_flag" getter="get_draw_flag" default="true"> If [code]true[/code], the texture's transparency and the opacity are used to make those parts of the sprite invisible. diff --git a/doc/classes/StatusIndicator.xml b/doc/classes/StatusIndicator.xml new file mode 100644 index 0000000000..e1fcc35ad7 --- /dev/null +++ b/doc/classes/StatusIndicator.xml @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="StatusIndicator" inherits="Node" keywords="tray" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Application status indicator (aka notification area icon). + [b]Note:[/b] Status indicator is implemented on macOS and Windows. + </brief_description> + <description> + </description> + <tutorials> + </tutorials> + <members> + <member name="icon" type="Image" setter="set_icon" getter="get_icon"> + Status indicator icon. + </member> + <member name="tooltip" type="String" setter="set_tooltip" getter="get_tooltip" default=""""> + Status indicator tooltip. + </member> + <member name="visible" type="bool" setter="set_visible" getter="is_visible" default="true"> + If [code]true[/code], the status indicator is visible. + </member> + </members> + <signals> + <signal name="pressed"> + <param index="0" name="mouse_button" type="int" /> + <param index="1" name="mouse_position" type="Vector2i" /> + <description> + Emitted when the status indicator is pressed. + </description> + </signal> + </signals> +</class> diff --git a/doc/classes/StreamPeerGZIP.xml b/doc/classes/StreamPeerGZIP.xml index fc22f72df9..e3f8441d19 100644 --- a/doc/classes/StreamPeerGZIP.xml +++ b/doc/classes/StreamPeerGZIP.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="StreamPeerGZIP" inherits="StreamPeer" is_experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="StreamPeerGZIP" inherits="StreamPeer" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A stream peer that handles GZIP and deflate compression/decompression. </brief_description> diff --git a/doc/classes/String.xml b/doc/classes/String.xml index af4297afae..7592342602 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -41,7 +41,7 @@ </constructor> </constructors> <methods> - <method name="begins_with" qualifiers="const"> + <method name="begins_with" qualifiers="const" keywords="starts_with"> <return type="bool" /> <param index="0" name="text" type="String" /> <description> @@ -96,13 +96,14 @@ [gdscript] "move_local_x".capitalize() # Returns "Move Local X" "sceneFile_path".capitalize() # Returns "Scene File Path" + "2D, FPS, PNG".capitalize() # Returns "2d, Fps, Png" [/gdscript] [csharp] "move_local_x".Capitalize(); // Returns "Move Local X" "sceneFile_path".Capitalize(); // Returns "Scene File Path" + "2D, FPS, PNG".Capitalize(); // Returns "2d, Fps, Png" [/csharp] [/codeblocks] - [b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect. </description> </method> <method name="casecmp_to" qualifiers="const"> @@ -111,7 +112,7 @@ <description> Performs a case-sensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" and "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to], [method naturalcasecmp_to], and [method naturalnocasecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to], [method filecasecmp_to], and [method naturalcasecmp_to]. </description> </method> <method name="chr" qualifiers="static"> @@ -125,7 +126,7 @@ [/codeblock] </description> </method> - <method name="contains" qualifiers="const"> + <method name="contains" qualifiers="const" keywords="includes, has"> <return type="bool" /> <param index="0" name="what" type="String" /> <description> @@ -183,6 +184,22 @@ Returns a string with [param chars] characters erased starting from [param position]. If [param chars] goes beyond the string's length given the specified [param position], fewer characters will be erased from the returned string. Returns an empty string if either [param position] or [param chars] is negative. Returns the original string unmodified if [param chars] is [code]0[/code]. </description> </method> + <method name="filecasecmp_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="String" /> + <description> + Like [method naturalcasecmp_to] but prioritises strings that begin with periods ([code].[/code]) and underscores ([code]_[/code]) before any other character. Useful when sorting folders or file names. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method filenocasecmp_to], [method naturalcasecmp_to], and [method casecmp_to]. + </description> + </method> + <method name="filenocasecmp_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="String" /> + <description> + Like [method naturalnocasecmp_to] but prioritises strings that begin with periods ([code].[/code]) and underscores ([code]_[/code]) before any other character. Useful when sorting folders or file names. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method filecasecmp_to], [method naturalnocasecmp_to], and [method nocasecmp_to]. + </description> + </method> <method name="find" qualifiers="const"> <return type="int" /> <param index="0" name="what" type="String" /> @@ -318,7 +335,7 @@ <return type="int" /> <description> Returns the 32-bit hash value representing the string's contents. - [b]Note:[/b] Strings with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the countrary, strings with different hash values are guaranteed to be different. + [b]Note:[/b] Strings with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the contrary, strings with different hash values are guaranteed to be different. </description> </method> <method name="hex_decode" qualifiers="const"> @@ -530,7 +547,7 @@ [/codeblock] </description> </method> - <method name="length" qualifiers="const"> + <method name="length" qualifiers="const" keywords="size"> <return type="int" /> <description> Returns the number of characters in the string. Empty strings ([code]""[/code]) always return [code]0[/code]. See also [method is_empty]. @@ -585,7 +602,7 @@ Performs a [b]case-sensitive[/b], [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit's value. A sorted sequence of numbered strings will be [code]["1", "2", "3", ...][/code], not [code]["1", "10", "2", "3", ...][/code]. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalnocasecmp_to], [method nocasecmp_to], and [method casecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalnocasecmp_to], [method filecasecmp_to], and [method nocasecmp_to]. </description> </method> <method name="naturalnocasecmp_to" qualifiers="const"> @@ -595,7 +612,7 @@ Performs a [b]case-insensitive[/b], [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit's value. A sorted sequence of numbered strings will be [code]["1", "2", "3", ...][/code], not [code]["1", "10", "2", "3", ...][/code]. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalcasecmp_to], [method nocasecmp_to], and [method casecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalcasecmp_to], [method filenocasecmp_to], and [method casecmp_to]. </description> </method> <method name="nocasecmp_to" qualifiers="const"> @@ -604,7 +621,7 @@ <description> Performs a [b]case-insensitive[/b] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to], [method naturalcasecmp_to], and [method naturalnocasecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to], [method filenocasecmp_to], and [method naturalnocasecmp_to]. </description> </method> <method name="num" qualifiers="static"> @@ -650,8 +667,8 @@ [codeblocks] [gdscript] var n = -5.2e8 - print(n) # Prints -520000000 - print(String.NumScientific(n)) # Prints -5.2e+08 + print(n) # Prints -520000000 + print(String.num_scientific(n)) # Prints -5.2e+08 [/gdscript] [csharp] // This method is not implemented in C#. @@ -949,7 +966,7 @@ <method name="to_lower" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to lowercase. + Returns the string converted to [code]lowercase[/code]. </description> </method> <method name="to_pascal_case" qualifiers="const"> @@ -962,12 +979,25 @@ <return type="String" /> <description> Returns the string converted to [code]snake_case[/code]. + [b]Note:[/b] Numbers followed by a [i]single[/i] letter are not separated in the conversion to keep some words (such as "2D") together. + [codeblocks] + [gdscript] + "Node2D".to_snake_case() # Returns "node_2d" + "2nd place".to_snake_case() # Returns "2_nd_place" + "Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder" + [/gdscript] + [csharp] + "Node2D".ToSnakeCase(); // Returns "node_2d" + "2nd place".ToSnakeCase(); // Returns "2_nd_place" + "Texture3DAssetFolder".ToSnakeCase(); // Returns "texture_3d_asset_folder" + [/csharp] + [/codeblocks] </description> </method> <method name="to_upper" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to uppercase. + Returns the string converted to [code]UPPERCASE[/code]. </description> </method> <method name="to_utf8_buffer" qualifiers="const"> diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml index 1c5032be9b..e837b65199 100644 --- a/doc/classes/StringName.xml +++ b/doc/classes/StringName.xml @@ -5,9 +5,10 @@ </brief_description> <description> [StringName]s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). Two [StringName]s with the same value are the same object. Comparing them is extremely fast compared to regular [String]s. - You will usually just pass a [String] to methods expecting a [StringName] and it will be automatically converted, but you may occasionally want to construct a [StringName] ahead of time with the [StringName] constructor or, in GDScript, the literal syntax [code]&"example"[/code]. + You will usually pass a [String] to methods expecting a [StringName] and it will be automatically converted (often at compile time), but in rare cases you can construct a [StringName] ahead of time with the [StringName] constructor or, in GDScript, the literal syntax [code]&"example"[/code]. Manually constructing a [StringName] allows you to control when the conversion from [String] occurs or to use the literal and prevent conversions entirely. See also [NodePath], which is a similar concept specifically designed to store pre-parsed scene tree paths. All of [String]'s methods are available in this class too. They convert the [StringName] into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired. + [b]Note:[/b] In C#, an explicit conversion to [code]System.String[/code] is required to use the methods listed on this page. Use the [code]ToString()[/code] method to cast a [StringName] to a string, and then use the equivalent methods in [code]System.String[/code] or [code]StringExtensions[/code]. [b]Note:[/b] In a boolean context, a [StringName] will evaluate to [code]false[/code] if it is empty ([code]StringName("")[/code]). Otherwise, a [StringName] will always evaluate to [code]true[/code]. The [code]not[/code] operator cannot be used. Instead, [method is_empty] should be used to check for empty [StringName]s. </description> <tutorials> @@ -90,13 +91,14 @@ [gdscript] "move_local_x".capitalize() # Returns "Move Local X" "sceneFile_path".capitalize() # Returns "Scene File Path" + "2D, FPS, PNG".capitalize() # Returns "2d, Fps, Png" [/gdscript] [csharp] "move_local_x".Capitalize(); // Returns "Move Local X" "sceneFile_path".Capitalize(); // Returns "Scene File Path" + "2D, FPS, PNG".Capitalize(); // Returns "2d, Fps, Png" [/csharp] [/codeblocks] - [b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect. </description> </method> <method name="casecmp_to" qualifiers="const"> @@ -105,7 +107,7 @@ <description> Performs a case-sensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" and "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to], [method naturalcasecmp_to], and [method naturalnocasecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to], [method filecasecmp_to], and [method naturalcasecmp_to]. </description> </method> <method name="contains" qualifiers="const"> @@ -166,6 +168,22 @@ Returns a string with [param chars] characters erased starting from [param position]. If [param chars] goes beyond the string's length given the specified [param position], fewer characters will be erased from the returned string. Returns an empty string if either [param position] or [param chars] is negative. Returns the original string unmodified if [param chars] is [code]0[/code]. </description> </method> + <method name="filecasecmp_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="String" /> + <description> + Like [method naturalcasecmp_to] but prioritises strings that begin with periods ([code].[/code]) and underscores ([code]_[/code]) before any other character. Useful when sorting folders or file names. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method filenocasecmp_to], [method naturalcasecmp_to], and [method casecmp_to]. + </description> + </method> + <method name="filenocasecmp_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="String" /> + <description> + Like [method naturalnocasecmp_to] but prioritises strings that begin with periods ([code].[/code]) and underscores ([code]_[/code]) before any other character. Useful when sorting folders or file names. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method filecasecmp_to], [method naturalnocasecmp_to], and [method nocasecmp_to]. + </description> + </method> <method name="find" qualifiers="const"> <return type="int" /> <param index="0" name="what" type="String" /> @@ -301,7 +319,7 @@ <return type="int" /> <description> Returns the 32-bit hash value representing the string's contents. - [b]Note:[/b] Strings with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the countrary, strings with different hash values are guaranteed to be different. + [b]Note:[/b] Strings with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the contrary, strings with different hash values are guaranteed to be different. </description> </method> <method name="hex_decode" qualifiers="const"> @@ -505,7 +523,7 @@ [/codeblock] </description> </method> - <method name="length" qualifiers="const"> + <method name="length" qualifiers="const" keywords="size"> <return type="int" /> <description> Returns the number of characters in the string. Empty strings ([code]""[/code]) always return [code]0[/code]. See also [method is_empty]. @@ -560,7 +578,7 @@ Performs a [b]case-sensitive[/b], [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit's value. A sorted sequence of numbered strings will be [code]["1", "2", "3", ...][/code], not [code]["1", "10", "2", "3", ...][/code]. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalnocasecmp_to], [method nocasecmp_to], and [method casecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalnocasecmp_to], [method filecasecmp_to], and [method nocasecmp_to]. </description> </method> <method name="naturalnocasecmp_to" qualifiers="const"> @@ -570,7 +588,7 @@ Performs a [b]case-insensitive[/b], [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit's value. A sorted sequence of numbered strings will be [code]["1", "2", "3", ...][/code], not [code]["1", "10", "2", "3", ...][/code]. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalcasecmp_to], [method nocasecmp_to], and [method casecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method naturalcasecmp_to], [method filenocasecmp_to], and [method casecmp_to]. </description> </method> <method name="nocasecmp_to" qualifiers="const"> @@ -579,7 +597,7 @@ <description> Performs a [b]case-insensitive[/b] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. - To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to], [method naturalcasecmp_to], and [method naturalnocasecmp_to]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to], [method filenocasecmp_to], and [method naturalnocasecmp_to]. </description> </method> <method name="pad_decimals" qualifiers="const"> @@ -856,7 +874,7 @@ <method name="to_lower" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to lowercase. + Returns the string converted to [code]lowercase[/code]. </description> </method> <method name="to_pascal_case" qualifiers="const"> @@ -869,12 +887,25 @@ <return type="String" /> <description> Returns the string converted to [code]snake_case[/code]. + [b]Note:[/b] Numbers followed by a [i]single[/i] letter are not separated in the conversion to keep some words (such as "2D") together. + [codeblocks] + [gdscript] + "Node2D".to_snake_case() # Returns "node_2d" + "2nd place".to_snake_case() # Returns "2_nd_place" + "Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder" + [/gdscript] + [csharp] + "Node2D".ToSnakeCase(); // Returns "node_2d" + "2nd place".ToSnakeCase(); // Returns "2_nd_place" + "Texture3DAssetFolder".ToSnakeCase(); // Returns "texture_3d_asset_folder" + [/csharp] + [/codeblocks] </description> </method> <method name="to_upper" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to uppercase. + Returns the string converted to [code]UPPERCASE[/code]. </description> </method> <method name="to_utf8_buffer" qualifiers="const"> diff --git a/doc/classes/StyleBoxLine.xml b/doc/classes/StyleBoxLine.xml index 8958cf9fc8..5f9d3332f2 100644 --- a/doc/classes/StyleBoxLine.xml +++ b/doc/classes/StyleBoxLine.xml @@ -9,7 +9,7 @@ <tutorials> </tutorials> <members> - <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)"> + <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)" keywords="colour"> The line's color. </member> <member name="grow_begin" type="float" setter="set_grow_begin" getter="get_grow_begin" default="1.0"> diff --git a/doc/classes/SubViewportContainer.xml b/doc/classes/SubViewportContainer.xml index e7d7883c78..b7d097cc91 100644 --- a/doc/classes/SubViewportContainer.xml +++ b/doc/classes/SubViewportContainer.xml @@ -11,7 +11,7 @@ <tutorials> </tutorials> <methods> - <method name="_propagate_input_event" qualifiers="virtual const"> + <method name="_propagate_input_event" qualifiers="virtual const" experimental=""> <return type="bool" /> <param index="0" name="event" type="InputEvent" /> <description> diff --git a/doc/classes/SurfaceTool.xml b/doc/classes/SurfaceTool.xml index 5562342eac..094275c349 100644 --- a/doc/classes/SurfaceTool.xml +++ b/doc/classes/SurfaceTool.xml @@ -119,13 +119,12 @@ Removes the index array by expanding the vertex array. </description> </method> - <method name="generate_lod" is_deprecated="true"> + <method name="generate_lod" deprecated="This method is unused internally, as it does not preserve normals or UVs. Consider using [method ImporterMesh.generate_lods] instead."> <return type="PackedInt32Array" /> <param index="0" name="nd_threshold" type="float" /> <param index="1" name="target_index_count" type="int" default="3" /> <description> - Generates a LOD for a given [param nd_threshold] in linear units (square root of quadric error metric), using at most [param target_index_count] indices. - [i]Deprecated.[/i] Unused internally and neglects to preserve normals or UVs. Consider using [method ImporterMesh.generate_lods] instead. + Generates an LOD for a given [param nd_threshold] in linear units (square root of quadric error metric), using at most [param target_index_count] indices. </description> </method> <method name="generate_normals"> diff --git a/doc/classes/SystemFont.xml b/doc/classes/SystemFont.xml index 239bcc257c..38d6e27c85 100644 --- a/doc/classes/SystemFont.xml +++ b/doc/classes/SystemFont.xml @@ -7,7 +7,7 @@ [SystemFont] loads a font from a system font with the first matching name from [member font_names]. It will attempt to match font style, but it's not guaranteed. The returned font might be part of a font collection or be a variable font with OpenType "weight", "width" and/or "italic" features set. - You can create [FontVariation] of the system font for fine control over its features. + You can create [FontVariation] of the system font for precise control over its features. [b]Note:[/b] This class is implemented on iOS, Linux, macOS and Windows, on other platforms it will fallback to default theme font. </description> <tutorials> @@ -19,6 +19,9 @@ <member name="antialiasing" type="int" setter="set_antialiasing" getter="get_antialiasing" enum="TextServer.FontAntialiasing" default="1"> Font anti-aliasing mode. </member> + <member name="disable_embedded_bitmaps" type="bool" setter="set_disable_embedded_bitmaps" getter="get_disable_embedded_bitmaps" default="true"> + If set to [code]true[/code], embedded font bitmap loading is disabled (bitmap-only and color fonts ignore this property). + </member> <member name="font_italic" type="bool" setter="set_font_italic" getter="get_font_italic" default="false"> If set to [code]true[/code], italic or oblique font is preferred. </member> diff --git a/doc/classes/TCPServer.xml b/doc/classes/TCPServer.xml index f84983de49..1daf84b5f1 100644 --- a/doc/classes/TCPServer.xml +++ b/doc/classes/TCPServer.xml @@ -36,7 +36,7 @@ Listen on the [param port] binding to [param bind_address]. If [param bind_address] is set as [code]"*"[/code] (default), the server will listen on all available addresses (both IPv4 and IPv6). If [param bind_address] is set as [code]"0.0.0.0"[/code] (for IPv4) or [code]"::"[/code] (for IPv6), the server will listen on all available addresses matching that IP type. - If [param bind_address] is set to any valid address (e.g. [code]"192.168.1.101"[/code], [code]"::1"[/code], etc), the server will only listen on the interface with that addresses (or fail if no interface with the given address exists). + If [param bind_address] is set to any valid address (e.g. [code]"192.168.1.101"[/code], [code]"::1"[/code], etc.), the server will only listen on the interface with that address (or fail if no interface with the given address exists). </description> </method> <method name="stop"> diff --git a/doc/classes/TabBar.xml b/doc/classes/TabBar.xml index 165b187710..a2beef81eb 100644 --- a/doc/classes/TabBar.xml +++ b/doc/classes/TabBar.xml @@ -229,8 +229,11 @@ <member name="clip_tabs" type="bool" setter="set_clip_tabs" getter="get_clip_tabs" default="true"> If [code]true[/code], tabs overflowing this node's width will be hidden, displaying two navigation buttons instead. Otherwise, this node's minimum size is updated so that all tabs are visible. </member> - <member name="current_tab" type="int" setter="set_current_tab" getter="get_current_tab" default="0"> - Select tab at index [code]tab_idx[/code]. + <member name="current_tab" type="int" setter="set_current_tab" getter="get_current_tab" default="-1"> + The index of the current selected tab. A value of [code]-1[/code] means that no tab is selected and can only be set when [member deselect_enabled] is [code]true[/code] or if all tabs are hidden or disabled. + </member> + <member name="deselect_enabled" type="bool" setter="set_deselect_enabled" getter="get_deselect_enabled" default="false"> + If [code]true[/code], all tabs can be deselected so that no tab is selected. Click on the current tab to deselect it. </member> <member name="drag_to_rearrange_enabled" type="bool" setter="set_drag_to_rearrange_enabled" getter="get_drag_to_rearrange_enabled" default="false"> If [code]true[/code], tabs can be rearranged with mouse drag. @@ -357,7 +360,7 @@ <theme_item name="font_hovered_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)"> Font color of the currently hovered tab. Does not apply to the selected tab. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the tab name. </theme_item> <theme_item name="font_selected_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)"> diff --git a/doc/classes/TabContainer.xml b/doc/classes/TabContainer.xml index b3a9264569..b0e3f67791 100644 --- a/doc/classes/TabContainer.xml +++ b/doc/classes/TabContainer.xml @@ -181,8 +181,13 @@ <member name="clip_tabs" type="bool" setter="set_clip_tabs" getter="get_clip_tabs" default="true"> If [code]true[/code], tabs overflowing this node's width will be hidden, displaying two navigation buttons instead. Otherwise, this node's minimum size is updated so that all tabs are visible. </member> - <member name="current_tab" type="int" setter="set_current_tab" getter="get_current_tab" default="0"> + <member name="current_tab" type="int" setter="set_current_tab" getter="get_current_tab" default="-1"> The current tab index. When set, this index's [Control] node's [code]visible[/code] property is set to [code]true[/code] and all others are set to [code]false[/code]. + A value of [code]-1[/code] means that no tab is selected. + </member> + <member name="deselect_enabled" type="bool" setter="set_deselect_enabled" getter="get_deselect_enabled" default="false"> + If [code]true[/code], all tabs can be deselected so that no tab is selected. Click on the [member current_tab] to deselect it. + Only the tab header will be shown if no tabs are selected. </member> <member name="drag_to_rearrange_enabled" type="bool" setter="set_drag_to_rearrange_enabled" getter="get_drag_to_rearrange_enabled" default="false"> If [code]true[/code], tabs can be rearranged with mouse drag. @@ -193,6 +198,9 @@ <member name="tab_focus_mode" type="int" setter="set_tab_focus_mode" getter="get_tab_focus_mode" enum="Control.FocusMode" default="2"> The focus access mode for the internal [TabBar] node. </member> + <member name="tabs_position" type="int" setter="set_tabs_position" getter="get_tabs_position" enum="TabContainer.TabPosition" default="0"> + Sets the position of the tab bar. See [enum TabPosition] for details. + </member> <member name="tabs_rearrange_group" type="int" setter="set_tabs_rearrange_group" getter="get_tabs_rearrange_group" default="-1"> [TabContainer]s with the same rearrange group ID will allow dragging the tabs between them. Enable drag with [member drag_to_rearrange_enabled]. Setting this to [code]-1[/code] will disable rearranging between [TabContainer]s. @@ -201,7 +209,7 @@ If [code]true[/code], tabs are visible. If [code]false[/code], tabs' content and titles are hidden. </member> <member name="use_hidden_tabs_for_min_size" type="bool" setter="set_use_hidden_tabs_for_min_size" getter="get_use_hidden_tabs_for_min_size" default="false"> - If [code]true[/code], children [Control] nodes that are hidden have their minimum size take into account in the total, instead of only the currently visible one. + If [code]true[/code], child [Control] nodes that are hidden have their minimum size take into account in the total, instead of only the currently visible one. </member> </members> <signals> @@ -247,6 +255,17 @@ </description> </signal> </signals> + <constants> + <constant name="POSITION_TOP" value="0" enum="TabPosition"> + Places the tab bar at the top. + </constant> + <constant name="POSITION_BOTTOM" value="1" enum="TabPosition"> + Places the tab bar at the bottom. The tab bar's [StyleBox] will be flipped vertically. + </constant> + <constant name="POSITION_MAX" value="2" enum="TabPosition"> + Represents the size of the [enum TabPosition] enum. + </constant> + </constants> <theme_items> <theme_item name="drop_mark_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> Modulation color for the [theme_item drop_mark] icon. @@ -257,7 +276,7 @@ <theme_item name="font_hovered_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)"> Font color of the currently hovered tab. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the tab name. </theme_item> <theme_item name="font_selected_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)"> diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index 4148c4eb09..db0c1f17b0 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="TextEdit" inherits="Control" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="TextEdit" inherits="Control" keywords="textarea" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A multiline text editor. </brief_description> @@ -101,6 +101,12 @@ Adjust the viewport so the caret is visible. </description> </method> + <method name="apply_ime"> + <return type="void" /> + <description> + Applies text from the [url=https://en.wikipedia.org/wiki/Input_method]Input Method Editor[/url] (IME) to each caret and closes the IME if it is open. + </description> + </method> <method name="backspace"> <return type="void" /> <param index="0" name="caret_index" type="int" default="-1" /> @@ -114,6 +120,12 @@ Starts a multipart edit. All edits will be treated as one action until [method end_complex_operation] is called. </description> </method> + <method name="cancel_ime"> + <return type="void" /> + <description> + Closes the [url=https://en.wikipedia.org/wiki/Input_method]Input Method Editor[/url] (IME) if it is open. Any text in the IME will be lost. + </description> + </method> <method name="center_viewport_to_caret"> <return type="void" /> <param index="0" name="caret_index" type="int" default="0" /> @@ -243,7 +255,7 @@ <return type="int" enum="TextEdit.GutterType" /> <param index="0" name="gutter" type="int" /> <description> - Returns the type of the gutter at the given index. + Returns the type of the gutter at the given index. Gutters can contain icons, text, or custom visuals. See [enum TextEdit.GutterType] for options. </description> </method> <method name="get_gutter_width" qualifiers="const"> @@ -317,7 +329,7 @@ <param index="0" name="line" type="int" /> <param index="1" name="gutter" type="int" /> <description> - Returns the icon currently in [param gutter] at [param line]. + Returns the icon currently in [param gutter] at [param line]. This only works when the gutter type is [constant GUTTER_TYPE_ICON] (see [method set_gutter_type]). </description> </method> <method name="get_line_gutter_item_color" qualifiers="const"> @@ -341,7 +353,7 @@ <param index="0" name="line" type="int" /> <param index="1" name="gutter" type="int" /> <description> - Returns the text currently in [param gutter] at [param line]. + Returns the text currently in [param gutter] at [param line]. This only works when the gutter type is [constant GUTTER_TYPE_STRING] (see [method set_gutter_type]). </description> </method> <method name="get_line_height" qualifiers="const"> @@ -611,7 +623,7 @@ <method name="has_ime_text" qualifiers="const"> <return type="bool" /> <description> - Returns if the user has IME text. + Returns [code]true[/code] if the user has text in the [url=https://en.wikipedia.org/wiki/Input_method]Input Method Editor[/url] (IME). </description> </method> <method name="has_redo" qualifiers="const"> @@ -885,7 +897,7 @@ <param index="0" name="column" type="int" /> <param index="1" name="draw_callback" type="Callable" /> <description> - Set a custom draw method for the gutter. The callback method must take the following args: [code]line: int, gutter: int, Area: Rect2[/code]. + Set a custom draw method for the gutter. The callback method must take the following args: [code]line: int, gutter: int, Area: Rect2[/code]. This only works when the gutter type is [constant GUTTER_TYPE_CUSTOM] (see [method set_gutter_type]). </description> </method> <method name="set_gutter_draw"> @@ -917,7 +929,7 @@ <param index="0" name="gutter" type="int" /> <param index="1" name="type" type="int" enum="TextEdit.GutterType" /> <description> - Sets the type of gutter. + Sets the type of gutter. Gutters can contain icons, text, or custom visuals. See [enum TextEdit.GutterType] for options. </description> </method> <method name="set_gutter_width"> @@ -983,7 +995,7 @@ <param index="1" name="gutter" type="int" /> <param index="2" name="icon" type="Texture2D" /> <description> - Sets the icon for [param gutter] on [param line] to [param icon]. + Sets the icon for [param gutter] on [param line] to [param icon]. This only works when the gutter type is [constant GUTTER_TYPE_ICON] (see [method set_gutter_type]). </description> </method> <method name="set_line_gutter_item_color"> @@ -1010,7 +1022,7 @@ <param index="1" name="gutter" type="int" /> <param index="2" name="text" type="String" /> <description> - Sets the text for [param gutter] on [param line] to [param text]. + Sets the text for [param gutter] on [param line] to [param text]. This only works when the gutter type is [constant GUTTER_TYPE_STRING] (see [method set_gutter_type]). </description> </method> <method name="set_overtype_mode_enabled"> @@ -1058,6 +1070,12 @@ Provide custom tooltip text. The callback method must take the following args: [code]hovered_word: String[/code]. </description> </method> + <method name="skip_selection_for_next_occurrence"> + <return type="void" /> + <description> + Moves a selection and a caret for the next occurrence of the current selection. If there is no active selection, moves to the next occurrence of the word under caret. + </description> + </method> <method name="start_action"> <return type="void" /> <param index="0" name="action" type="int" enum="TextEdit.EditAction" /> @@ -1106,7 +1124,7 @@ </member> <member name="caret_move_on_right_click" type="bool" setter="set_move_caret_on_right_click_enabled" getter="is_move_caret_on_right_click_enabled" default="true"> If [code]true[/code], a right-click moves the caret at the mouse position before displaying the context menu. - If [code]false[/code], the context menu disregards mouse location. + If [code]false[/code], the context menu ignores mouse location. </member> <member name="caret_multiple" type="bool" setter="set_multiple_carets_enabled" getter="is_multiple_carets_enabled" default="true"> Sets if multiple carets are allowed. @@ -1114,6 +1132,7 @@ <member name="caret_type" type="int" setter="set_caret_type" getter="get_caret_type" enum="TextEdit.CaretType" default="0"> Set the type of caret to draw. </member> + <member name="clip_contents" type="bool" setter="set_clip_contents" getter="is_clipping_contents" overrides="Control" default="true" /> <member name="context_menu_enabled" type="bool" setter="set_context_menu_enabled" getter="is_context_menu_enabled" default="true"> If [code]true[/code], a right-click displays the context menu. </member> @@ -1132,7 +1151,7 @@ <member name="draw_tabs" type="bool" setter="set_draw_tabs" getter="is_drawing_tabs" default="false"> If [code]true[/code], the "tab" character will have a visible representation. </member> - <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true"> + <member name="editable" type="bool" setter="set_editable" getter="is_editable" default="true" keywords="readonly, disabled, enabled"> If [code]false[/code], existing text cannot be modified and new text cannot be added. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> @@ -1142,6 +1161,9 @@ <member name="highlight_current_line" type="bool" setter="set_highlight_current_line" getter="is_highlight_current_line_enabled" default="false"> If [code]true[/code], the line containing the cursor is highlighted. </member> + <member name="indent_wrapped_lines" type="bool" setter="set_indent_wrapped_lines" getter="is_indent_wrapped_lines" default="false"> + If [code]true[/code], all wrapped lines are indented to the same amount as the unwrapped line. + </member> <member name="language" type="String" setter="set_language" getter="get_language" default=""""> Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead. </member> @@ -1391,13 +1413,13 @@ Line wrapping occurs at the control boundary, beyond what would normally be visible. </constant> <constant name="GUTTER_TYPE_STRING" value="0" enum="GutterType"> - Draw a string. + When a gutter is set to string using [method set_gutter_type], it is used to contain text set via the [method set_line_gutter_text] method. </constant> <constant name="GUTTER_TYPE_ICON" value="1" enum="GutterType"> - Draw an icon. + When a gutter is set to icon using [method set_gutter_type], it is used to contain an icon set via the [method set_line_gutter_icon] method. </constant> <constant name="GUTTER_TYPE_CUSTOM" value="2" enum="GutterType"> - Custom draw. + When a gutter is set to custom using [method set_gutter_type], it is used to contain custom visuals controlled by a callback method set via the [method set_gutter_custom_draw] method. </constant> </constants> <theme_items> @@ -1416,7 +1438,7 @@ <theme_item name="font_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)"> Sets the font [Color]. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the [TextEdit]. </theme_item> <theme_item name="font_placeholder_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 0.6)"> @@ -1468,7 +1490,7 @@ <theme_item name="normal" data_type="style" type="StyleBox"> Sets the [StyleBox] of this [TextEdit]. </theme_item> - <theme_item name="read_only" data_type="style" type="StyleBox"> + <theme_item name="read_only" data_type="style" type="StyleBox" keywords="enabled, disabled, editable"> Sets the [StyleBox] of this [TextEdit] when [member editable] is disabled. </theme_item> </theme_items> diff --git a/doc/classes/TextLine.xml b/doc/classes/TextLine.xml index e65006716d..2e4a3f7e4c 100644 --- a/doc/classes/TextLine.xml +++ b/doc/classes/TextLine.xml @@ -151,6 +151,9 @@ <member name="direction" type="int" setter="set_direction" getter="get_direction" enum="TextServer.Direction" default="0"> Text writing direction. </member> + <member name="ellipsis_char" type="String" setter="set_ellipsis_char" getter="get_ellipsis_char" default=""…""> + Ellipsis character used for text clipping. + </member> <member name="flags" type="int" setter="set_flags" getter="get_flags" enum="TextServer.JustificationFlag" is_bitfield="true" default="3"> Line alignment rules. For more info see [TextServer]. </member> diff --git a/doc/classes/TextMesh.xml b/doc/classes/TextMesh.xml index 00c6b0b1a8..9e705311c5 100644 --- a/doc/classes/TextMesh.xml +++ b/doc/classes/TextMesh.xml @@ -53,6 +53,7 @@ </member> <member name="text" type="String" setter="set_text" getter="get_text" default=""""> The text to generate mesh from. + [b]Note:[/b] Due to being a [Resource], it doesn't follow the rules of [member Node.auto_translate_mode]. If disabling translation is desired, it should be done manually with [method Object.set_message_translation]. </member> <member name="text_direction" type="int" setter="set_text_direction" getter="get_text_direction" enum="TextServer.Direction" default="0"> Base text writing direction. diff --git a/doc/classes/TextParagraph.xml b/doc/classes/TextParagraph.xml index a8a4c3a764..541078ed22 100644 --- a/doc/classes/TextParagraph.xml +++ b/doc/classes/TextParagraph.xml @@ -274,6 +274,9 @@ <member name="direction" type="int" setter="set_direction" getter="get_direction" enum="TextServer.Direction" default="0"> Text writing direction. </member> + <member name="ellipsis_char" type="String" setter="set_ellipsis_char" getter="get_ellipsis_char" default=""…""> + Ellipsis character used for text clipping. + </member> <member name="justification_flags" type="int" setter="set_justification_flags" getter="get_justification_flags" enum="TextServer.JustificationFlag" is_bitfield="true" default="163"> Line fill alignment rules. For more info see [enum TextServer.JustificationFlag]. </member> diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml index f4246a8c50..c0cd7f79e7 100644 --- a/doc/classes/TextServer.xml +++ b/doc/classes/TextServer.xml @@ -27,7 +27,7 @@ <param index="0" name="direction" type="int" enum="TextServer.Direction" default="0" /> <param index="1" name="orientation" type="int" enum="TextServer.Orientation" default="0" /> <description> - Creates new buffer for complex text layout, with the given [param direction] and [param orientation]. To free the resulting buffer, use [method free_rid] method. + Creates a new buffer for complex text layout, with the given [param direction] and [param orientation]. To free the resulting buffer, use [method free_rid] method. [b]Note:[/b] Direction is ignored if server does not support [constant FEATURE_BIDI_LAYOUT] feature (supported by [TextServerAdvanced]). [b]Note:[/b] Orientation is ignored if server does not support [constant FEATURE_VERTICAL_LAYOUT] feature (supported by [TextServerAdvanced]). </description> @@ -48,7 +48,7 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="Vector2i" /> <description> - Removes all rendered glyphs information from the cache entry. + Removes all rendered glyph information from the cache entry. [b]Note:[/b] This function will not remove textures associated with the glyphs, use [method font_remove_texture] to remove them manually. </description> </method> @@ -120,6 +120,13 @@ Returns the font ascent (number of pixels above the baseline). </description> </method> + <method name="font_get_baseline_offset" qualifiers="const"> + <return type="float" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns extra baseline offset (as a fraction of font height). + </description> + </method> <method name="font_get_char_from_glyph_index" qualifiers="const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> @@ -137,6 +144,13 @@ Returns the font descent (number of pixels below the baseline). </description> </method> + <method name="font_get_disable_embedded_bitmaps" qualifiers="const"> + <return type="bool" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns whether the font's embedded bitmap loading is disabled. + </description> + </method> <method name="font_get_embolden" qualifiers="const"> <return type="float" /> <param index="0" name="font_rid" type="RID" /> @@ -640,6 +654,14 @@ Sets the font ascent (number of pixels above the baseline). </description> </method> + <method name="font_set_baseline_offset"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="baseline_offset" type="float" /> + <description> + Sets extra baseline offset (as a fraction of font height). + </description> + </method> <method name="font_set_data"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -657,6 +679,14 @@ Sets the font descent (number of pixels below the baseline). </description> </method> + <method name="font_set_disable_embedded_bitmaps"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="disable_embedded_bitmaps" type="bool" /> + <description> + If set to [code]true[/code], embedded font bitmap loading is disabled (bitmap-only and color fonts ignore this property). + </description> + </method> <method name="font_set_embolden"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -926,7 +956,7 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="transform" type="Transform2D" /> <description> - Sets 2D transform, applied to the font outlines, can be used for slanting, flipping and rotating glyphs. + Sets 2D transform, applied to the font outlines, can be used for slanting, flipping, and rotating glyphs. For example, to simulate italic typeface by slanting, apply the following transform [code]Transform2D(1.0, slant, 0.0, 1.0, 0.0, 0.0)[/code]. </description> </method> @@ -1085,7 +1115,7 @@ <return type="int" /> <param index="0" name="name" type="String" /> <description> - Converts readable feature, variation, script or language name to OpenType tag. + Converts readable feature, variation, script, or language name to OpenType tag. </description> </method> <method name="parse_number" qualifiers="const"> @@ -1143,7 +1173,7 @@ <param index="3" name="size" type="int" /> <param index="4" name="opentype_features" type="Dictionary" default="{}" /> <description> - Changes text span font, font size and OpenType features, without changing the text. + Changes text span font, font size, and OpenType features, without changing the text. </description> </method> <method name="shaped_text_add_object"> @@ -1243,6 +1273,13 @@ Returns array of the composite character boundaries. </description> </method> + <method name="shaped_text_get_custom_ellipsis" qualifiers="const"> + <return type="int" /> + <param index="0" name="shaped" type="RID" /> + <description> + Returns ellipsis character used for text clipping. + </description> + </method> <method name="shaped_text_get_custom_punctuation" qualifiers="const"> <return type="String" /> <param index="0" name="shaped" type="RID" /> @@ -1345,6 +1382,22 @@ Breaks text to the lines and columns. Returns character ranges for each segment. </description> </method> + <method name="shaped_text_get_object_glyph" qualifiers="const"> + <return type="int" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="key" type="Variant" /> + <description> + Returns the glyph index of the inline object. + </description> + </method> + <method name="shaped_text_get_object_range" qualifiers="const"> + <return type="Vector2i" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="key" type="Variant" /> + <description> + Returns the character range of the inline object. + </description> + </method> <method name="shaped_text_get_object_rect" qualifiers="const"> <return type="Rect2" /> <param index="0" name="shaped" type="RID" /> @@ -1547,6 +1600,14 @@ Override ranges should cover full source text without overlaps. BiDi algorithm will be used on each range separately. </description> </method> + <method name="shaped_text_set_custom_ellipsis"> + <return type="void" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="char" type="int" /> + <description> + Sets ellipsis character used for text clipping. + </description> + </method> <method name="shaped_text_set_custom_punctuation"> <return type="void" /> <param index="0" name="shaped" type="RID" /> @@ -1675,6 +1736,16 @@ [b]Note:[/b] The result may be longer or shorter than the original. </description> </method> + <method name="string_to_title" qualifiers="const"> + <return type="String" /> + <param index="0" name="string" type="String" /> + <param index="1" name="language" type="String" default="""" /> + <description> + Returns the string converted to title case. + [b]Note:[/b] Casing is locale dependent and context sensitive if server support [constant FEATURE_CONTEXT_SENSITIVE_CASE_CONVERSION] feature (supported by [TextServerAdvanced]). + [b]Note:[/b] The result may be longer or shorter than the original. + </description> + </method> <method name="string_to_upper" qualifiers="const"> <return type="String" /> <param index="0" name="string" type="String" /> @@ -1697,7 +1768,7 @@ <return type="String" /> <param index="0" name="tag" type="int" /> <description> - Converts OpenType tag to readable feature, variation, script or language name. + Converts OpenType tag to readable feature, variation, script, or language name. </description> </method> </methods> @@ -1729,6 +1800,7 @@ Vertical BGR subpixel layout. </constant> <constant name="FONT_LCD_SUBPIXEL_LAYOUT_MAX" value="5" enum="FontLCDSubpixelLayout"> + Represents the size of the [enum FontLCDSubpixelLayout] enum. </constant> <constant name="DIRECTION_AUTO" value="0" enum="Direction"> Text direction is determined based on contents and current locale. @@ -1806,6 +1878,9 @@ <constant name="BREAK_TRIM_EDGE_SPACES" value="16" enum="LineBreakFlag" is_bitfield="true"> Remove edge spaces from the broken line segments. </constant> + <constant name="BREAK_TRIM_INDENT" value="32" enum="LineBreakFlag" is_bitfield="true"> + Subtract first line indentation width from all lines after the first one. + </constant> <constant name="VC_CHARS_BEFORE_SHAPING" value="0" enum="VisibleCharactersBehavior"> Trims text before the shaping. e.g, increasing [member Label.visible_characters] or [member RichTextLabel.visible_characters] value is visually identical to typing the text. </constant> @@ -1852,6 +1927,7 @@ Determines whether the ellipsis at the end of the text is enforced and may not be hidden. </constant> <constant name="OVERRUN_JUSTIFICATION_AWARE" value="16" enum="TextOverrunFlag" is_bitfield="true"> + Accounts for the text being justified before attempting to trim it (see [enum JustificationFlag]). </constant> <constant name="GRAPHEME_IS_VALID" value="1" enum="GraphemeFlag" is_bitfield="true"> Grapheme is supported by the font, and can be drawn. @@ -1892,6 +1968,9 @@ <constant name="GRAPHEME_IS_EMBEDDED_OBJECT" value="4096" enum="GraphemeFlag" is_bitfield="true"> Grapheme is an object replacement character for the embedded object. </constant> + <constant name="GRAPHEME_IS_SOFT_HYPHEN" value="8192" enum="GraphemeFlag" is_bitfield="true"> + Grapheme is a soft hyphen. + </constant> <constant name="HINTING_NONE" value="0" enum="Hinting"> Disables font hinting (smoother but less crisp). </constant> @@ -1990,6 +2069,7 @@ Spacing at the bottom of the line. </constant> <constant name="SPACING_MAX" value="4" enum="SpacingType"> + Represents the size of the [enum SpacingType] enum. </constant> <constant name="FONT_BOLD" value="1" enum="FontStyle" is_bitfield="true"> Font is bold. diff --git a/doc/classes/TextServerExtension.xml b/doc/classes/TextServerExtension.xml index 267e0b65cb..06a0daece6 100644 --- a/doc/classes/TextServerExtension.xml +++ b/doc/classes/TextServerExtension.xml @@ -12,17 +12,23 @@ <method name="_cleanup" qualifiers="virtual"> <return type="void" /> <description> + [b]Optional.[/b] + This method is called before text server is unregistered. </description> </method> <method name="_create_font" qualifiers="virtual"> <return type="RID" /> <description> + [b]Required.[/b] + Creates a new, empty font cache entry resource. </description> </method> <method name="_create_font_linked_variation" qualifiers="virtual"> <return type="RID" /> <param index="0" name="font_rid" type="RID" /> <description> + Optional, implement if font supports extra spacing or baseline offset. + Creates a new variation existing font which is reusing the same glyph cache and font data. </description> </method> <method name="_create_shaped_text" qualifiers="virtual"> @@ -30,6 +36,8 @@ <param index="0" name="direction" type="int" enum="TextServer.Direction" /> <param index="1" name="orientation" type="int" enum="TextServer.Orientation" /> <description> + [b]Required.[/b] + Creates a new buffer for complex text layout, with the given [param direction] and [param orientation]. </description> </method> <method name="_draw_hex_code_box" qualifiers="virtual const"> @@ -40,6 +48,8 @@ <param index="3" name="index" type="int" /> <param index="4" name="color" type="Color" /> <description> + [b]Optional.[/b] + Draws box displaying character hexadecimal code. </description> </method> <method name="_font_clear_glyphs" qualifiers="virtual"> @@ -47,6 +57,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="Vector2i" /> <description> + [b]Required.[/b] + Removes all rendered glyph information from the cache entry. </description> </method> <method name="_font_clear_kerning_map" qualifiers="virtual"> @@ -54,12 +66,16 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="int" /> <description> + [b]Optional.[/b] + Removes all kerning overrides. </description> </method> <method name="_font_clear_size_cache" qualifiers="virtual"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Required.[/b] + Removes all font sizes from the cache entry. </description> </method> <method name="_font_clear_textures" qualifiers="virtual"> @@ -67,6 +83,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="Vector2i" /> <description> + [b]Required.[/b] + Removes all textures from font cache entry. </description> </method> <method name="_font_draw_glyph" qualifiers="virtual const"> @@ -78,6 +96,8 @@ <param index="4" name="index" type="int" /> <param index="5" name="color" type="Color" /> <description> + [b]Required.[/b] + Draws single glyph into a canvas item at the position, using [param font_rid] at the size [param size]. </description> </method> <method name="_font_draw_glyph_outline" qualifiers="virtual const"> @@ -90,12 +110,16 @@ <param index="5" name="index" type="int" /> <param index="6" name="color" type="Color" /> <description> + [b]Required.[/b] + Draws single glyph outline of size [param outline_size] into a canvas item at the position, using [param font_rid] at the size [param size]. </description> </method> <method name="_font_get_antialiasing" qualifiers="virtual const"> <return type="int" enum="TextServer.FontAntialiasing" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font anti-aliasing mode. </description> </method> <method name="_font_get_ascent" qualifiers="virtual const"> @@ -103,6 +127,16 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="int" /> <description> + [b]Required.[/b] + Returns the font ascent (number of pixels above the baseline). + </description> + </method> + <method name="_font_get_baseline_offset" qualifiers="virtual const"> + <return type="float" /> + <param index="0" name="font_rid" type="RID" /> + <description> + [b]Optional.[/b] + Returns extra baseline offset (as a fraction of font height). </description> </method> <method name="_font_get_char_from_glyph_index" qualifiers="virtual const"> @@ -111,6 +145,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="glyph_index" type="int" /> <description> + [b]Required.[/b] + Returns character code associated with [param glyph_index], or [code]0[/code] if [param glyph_index] is invalid. </description> </method> <method name="_font_get_descent" qualifiers="virtual const"> @@ -118,47 +154,71 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="int" /> <description> + [b]Required.[/b] + Returns the font descent (number of pixels below the baseline). + </description> + </method> + <method name="_font_get_disable_embedded_bitmaps" qualifiers="virtual const"> + <return type="bool" /> + <param index="0" name="font_rid" type="RID" /> + <description> + [b]Optional.[/b] + Returns whether the font's embedded bitmap loading is disabled. </description> </method> <method name="_font_get_embolden" qualifiers="virtual const"> <return type="float" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font embolden strength. </description> </method> <method name="_font_get_face_count" qualifiers="virtual const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns number of faces in the TrueType / OpenType collection. </description> </method> <method name="_font_get_face_index" qualifiers="virtual const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns an active face index in the TrueType / OpenType collection. </description> </method> <method name="_font_get_fixed_size" qualifiers="virtual const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Required.[/b] + Returns bitmap font fixed size. </description> </method> <method name="_font_get_fixed_size_scale_mode" qualifiers="virtual const"> <return type="int" enum="TextServer.FixedSizeScaleMode" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Required.[/b] + Returns bitmap font scaling mode. </description> </method> <method name="_font_get_generate_mipmaps" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if font texture mipmap generation is enabled. </description> </method> <method name="_font_get_global_oversampling" qualifiers="virtual const"> <return type="float" /> <description> + [b]Optional.[/b] + Returns the font oversampling factor, shared by all fonts in the TextServer. </description> </method> <method name="_font_get_glyph_advance" qualifiers="virtual const"> @@ -167,6 +227,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Returns glyph advance (offset of the next glyph). </description> </method> <method name="_font_get_glyph_contours" qualifiers="virtual const"> @@ -175,6 +237,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="index" type="int" /> <description> + [b]Optional.[/b] + Returns outline contours of the glyph. </description> </method> <method name="_font_get_glyph_index" qualifiers="virtual const"> @@ -184,6 +248,8 @@ <param index="2" name="char" type="int" /> <param index="3" name="variation_selector" type="int" /> <description> + [b]Required.[/b] + Returns the glyph index of a [param char], optionally modified by the [param variation_selector]. </description> </method> <method name="_font_get_glyph_list" qualifiers="virtual const"> @@ -191,6 +257,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="Vector2i" /> <description> + [b]Required.[/b] + Returns list of rendered glyphs in the cache entry. </description> </method> <method name="_font_get_glyph_offset" qualifiers="virtual const"> @@ -199,6 +267,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Returns glyph offset from the baseline. </description> </method> <method name="_font_get_glyph_size" qualifiers="virtual const"> @@ -207,6 +277,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Returns size of the glyph. </description> </method> <method name="_font_get_glyph_texture_idx" qualifiers="virtual const"> @@ -215,6 +287,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Returns index of the cache texture containing the glyph. </description> </method> <method name="_font_get_glyph_texture_rid" qualifiers="virtual const"> @@ -223,6 +297,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Returns resource ID of the cache texture containing the glyph. </description> </method> <method name="_font_get_glyph_texture_size" qualifiers="virtual const"> @@ -231,6 +307,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Returns size of the cache texture containing the glyph. </description> </method> <method name="_font_get_glyph_uv_rect" qualifiers="virtual const"> @@ -239,12 +317,16 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Returns rectangle in the cache texture containing the glyph. </description> </method> <method name="_font_get_hinting" qualifiers="virtual const"> <return type="int" enum="TextServer.Hinting" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns the font hinting mode. Used by dynamic fonts only. </description> </method> <method name="_font_get_kerning" qualifiers="virtual const"> @@ -253,6 +335,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="glyph_pair" type="Vector2i" /> <description> + [b]Optional.[/b] + Returns kerning for the pair of glyphs. </description> </method> <method name="_font_get_kerning_list" qualifiers="virtual const"> @@ -260,6 +344,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="int" /> <description> + [b]Optional.[/b] + Returns list of the kerning overrides. </description> </method> <method name="_font_get_language_support_override" qualifiers="virtual"> @@ -267,48 +353,64 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if support override is enabled for the [param language]. </description> </method> <method name="_font_get_language_support_overrides" qualifiers="virtual"> <return type="PackedStringArray" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns list of language support overrides. </description> </method> <method name="_font_get_msdf_pixel_range" qualifiers="virtual const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns the width of the range around the shape between the minimum and maximum representable signed distance. </description> </method> <method name="_font_get_msdf_size" qualifiers="virtual const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns source font size used to generate MSDF textures. </description> </method> <method name="_font_get_name" qualifiers="virtual const"> <return type="String" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font family name. </description> </method> <method name="_font_get_opentype_feature_overrides" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font OpenType feature set override. </description> </method> <method name="_font_get_ot_name_strings" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns [Dictionary] with OpenType font name strings (localized font names, version, description, license information, sample text, etc.). </description> </method> <method name="_font_get_oversampling" qualifiers="virtual const"> <return type="float" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font oversampling factor, if set to [code]0.0[/code] global oversampling factor is used instead. Used by dynamic fonts only. </description> </method> <method name="_font_get_scale" qualifiers="virtual const"> @@ -316,6 +418,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="int" /> <description> + [b]Required.[/b] + Returns scaling factor of the color bitmap font. </description> </method> <method name="_font_get_script_support_override" qualifiers="virtual"> @@ -323,18 +427,24 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="script" type="String" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if support override is enabled for the [param script]. </description> </method> <method name="_font_get_script_support_overrides" qualifiers="virtual"> <return type="PackedStringArray" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns list of script support overrides. </description> </method> <method name="_font_get_size_cache_list" qualifiers="virtual const"> <return type="Vector2i[]" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Required.[/b] + Returns list of the font sizes in the cache. Each size is [Vector2i] with font size and outline size. </description> </method> <method name="_font_get_spacing" qualifiers="virtual const"> @@ -342,36 +452,48 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="spacing" type="int" enum="TextServer.SpacingType" /> <description> + [b]Optional.[/b] + Returns the spacing for [param spacing] (see [enum TextServer.SpacingType]) in pixels (not relative to the font size). </description> </method> <method name="_font_get_stretch" qualifiers="virtual const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. </description> </method> <method name="_font_get_style" qualifiers="virtual const"> <return type="int" enum="TextServer.FontStyle" is_bitfield="true" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font style flags, see [enum TextServer.FontStyle]. </description> </method> <method name="_font_get_style_name" qualifiers="virtual const"> <return type="String" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font style name. </description> </method> <method name="_font_get_subpixel_positioning" qualifiers="virtual const"> <return type="int" enum="TextServer.SubpixelPositioning" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns font subpixel glyph positioning mode. </description> </method> <method name="_font_get_supported_chars" qualifiers="virtual const"> <return type="String" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Required.[/b] + Returns a string containing all the characters available in the font. </description> </method> <method name="_font_get_texture_count" qualifiers="virtual const"> @@ -379,6 +501,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="Vector2i" /> <description> + [b]Required.[/b] + Returns number of textures used by font cache entry. </description> </method> <method name="_font_get_texture_image" qualifiers="virtual const"> @@ -387,6 +511,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="texture_index" type="int" /> <description> + [b]Required.[/b] + Returns font cache texture image data. </description> </method> <method name="_font_get_texture_offsets" qualifiers="virtual const"> @@ -395,12 +521,16 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="texture_index" type="int" /> <description> + [b]Optional.[/b] + Returns array containing glyph packing data. </description> </method> <method name="_font_get_transform" qualifiers="virtual const"> <return type="Transform2D" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns 2D transform applied to the font outlines. </description> </method> <method name="_font_get_underline_position" qualifiers="virtual const"> @@ -408,6 +538,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="int" /> <description> + [b]Required.[/b] + Returns pixel offset of the underline below the baseline. </description> </method> <method name="_font_get_underline_thickness" qualifiers="virtual const"> @@ -415,18 +547,24 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="int" /> <description> + [b]Required.[/b] + Returns thickness of the underline in pixels. </description> </method> <method name="_font_get_variation_coordinates" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns variation coordinates for the specified font cache entry. </description> </method> <method name="_font_get_weight" qualifiers="virtual const"> <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. </description> </method> <method name="_font_has_char" qualifiers="virtual const"> @@ -434,18 +572,24 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="char" type="int" /> <description> + [b]Required.[/b] + Returns [code]true[/code] if a Unicode [param char] is available in the font. </description> </method> <method name="_font_is_allow_system_fallback" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if system fonts can be automatically used as fallbacks. </description> </method> <method name="_font_is_force_autohinter" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if auto-hinting is supported and preferred over font built-in hinting. </description> </method> <method name="_font_is_language_supported" qualifiers="virtual const"> @@ -453,12 +597,16 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Returns [code]true[/code], if font supports given language ([url=https://en.wikipedia.org/wiki/ISO_639-1]ISO 639[/url] code). </description> </method> <method name="_font_is_multichannel_signed_distance_field" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if glyphs of all sizes are rendered using single multichannel signed distance field generated from the dynamic font vector data. </description> </method> <method name="_font_is_script_supported" qualifiers="virtual const"> @@ -466,6 +614,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="script" type="String" /> <description> + [b]Optional.[/b] + Returns [code]true[/code], if font supports given script (ISO 15924 code). </description> </method> <method name="_font_remove_glyph" qualifiers="virtual"> @@ -474,6 +624,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> + [b]Required.[/b] + Removes specified rendered glyph information from the cache entry. </description> </method> <method name="_font_remove_kerning" qualifiers="virtual"> @@ -482,6 +634,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="glyph_pair" type="Vector2i" /> <description> + [b]Optional.[/b] + Removes kerning override for the pair of glyphs. </description> </method> <method name="_font_remove_language_support_override" qualifiers="virtual"> @@ -489,6 +643,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Remove language support override. </description> </method> <method name="_font_remove_script_support_override" qualifiers="virtual"> @@ -496,6 +652,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="script" type="String" /> <description> + [b]Optional.[/b] + Removes script support override. </description> </method> <method name="_font_remove_size_cache" qualifiers="virtual"> @@ -503,6 +661,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="size" type="Vector2i" /> <description> + [b]Required.[/b] + Removes specified font size from the cache entry. </description> </method> <method name="_font_remove_texture" qualifiers="virtual"> @@ -511,6 +671,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="texture_index" type="int" /> <description> + [b]Required.[/b] + Removes specified texture from the cache entry. </description> </method> <method name="_font_render_glyph" qualifiers="virtual"> @@ -519,6 +681,8 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="index" type="int" /> <description> + [b]Optional.[/b] + Renders specified glyph to the font cache texture. </description> </method> <method name="_font_render_range" qualifiers="virtual"> @@ -528,6 +692,8 @@ <param index="2" name="start" type="int" /> <param index="3" name="end" type="int" /> <description> + [b]Optional.[/b] + Renders the range of characters to the font cache texture. </description> </method> <method name="_font_set_allow_system_fallback" qualifiers="virtual"> @@ -535,6 +701,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="allow_system_fallback" type="bool" /> <description> + [b]Optional.[/b] + If set to [code]true[/code], system fonts can be automatically used as fallbacks. </description> </method> <method name="_font_set_antialiasing" qualifiers="virtual"> @@ -542,6 +710,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="antialiasing" type="int" enum="TextServer.FontAntialiasing" /> <description> + [b]Optional.[/b] + Sets font anti-aliasing mode. </description> </method> <method name="_font_set_ascent" qualifiers="virtual"> @@ -550,6 +720,17 @@ <param index="1" name="size" type="int" /> <param index="2" name="ascent" type="float" /> <description> + [b]Required.[/b] + Sets the font ascent (number of pixels above the baseline). + </description> + </method> + <method name="_font_set_baseline_offset" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="baseline_offset" type="float" /> + <description> + [b]Optional.[/b] + Sets extra baseline offset (as a fraction of font height). </description> </method> <method name="_font_set_data" qualifiers="virtual"> @@ -557,6 +738,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="data" type="PackedByteArray" /> <description> + [b]Optional.[/b] + Sets font source data, e.g contents of the dynamic font source file. </description> </method> <method name="_font_set_data_ptr" qualifiers="virtual"> @@ -565,6 +748,8 @@ <param index="1" name="data_ptr" type="const uint8_t*" /> <param index="2" name="data_size" type="int" /> <description> + [b]Optional.[/b] + Sets pointer to the font source data, e.g contents of the dynamic font source file. </description> </method> <method name="_font_set_descent" qualifiers="virtual"> @@ -573,6 +758,17 @@ <param index="1" name="size" type="int" /> <param index="2" name="descent" type="float" /> <description> + [b]Required.[/b] + Sets the font descent (number of pixels below the baseline). + </description> + </method> + <method name="_font_set_disable_embedded_bitmaps" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="disable_embedded_bitmaps" type="bool" /> + <description> + [b]Optional.[/b] + If set to [code]true[/code], embedded font bitmap loading is disabled. </description> </method> <method name="_font_set_embolden" qualifiers="virtual"> @@ -580,6 +776,7 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="strength" type="float" /> <description> + Sets font embolden strength. If [param strength] is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness. </description> </method> <method name="_font_set_face_index" qualifiers="virtual"> @@ -587,6 +784,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="face_index" type="int" /> <description> + [b]Optional.[/b] + Sets an active face index in the TrueType / OpenType collection. </description> </method> <method name="_font_set_fixed_size" qualifiers="virtual"> @@ -594,6 +793,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="fixed_size" type="int" /> <description> + [b]Required.[/b] + Sets bitmap font fixed size. If set to value greater than zero, same cache entry will be used for all font sizes. </description> </method> <method name="_font_set_fixed_size_scale_mode" qualifiers="virtual"> @@ -601,6 +802,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="fixed_size_scale_mode" type="int" enum="TextServer.FixedSizeScaleMode" /> <description> + [b]Required.[/b] + Sets bitmap font scaling mode. This property is used only if [code]fixed_size[/code] is greater than zero. </description> </method> <method name="_font_set_force_autohinter" qualifiers="virtual"> @@ -608,6 +811,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="force_autohinter" type="bool" /> <description> + [b]Optional.[/b] + If set to [code]true[/code] auto-hinting is preferred over font built-in hinting. </description> </method> <method name="_font_set_generate_mipmaps" qualifiers="virtual"> @@ -615,12 +820,16 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="generate_mipmaps" type="bool" /> <description> + [b]Optional.[/b] + If set to [code]true[/code] font texture mipmap generation is enabled. </description> </method> <method name="_font_set_global_oversampling" qualifiers="virtual"> <return type="void" /> <param index="0" name="oversampling" type="float" /> <description> + [b]Optional.[/b] + Sets oversampling factor, shared by all font in the TextServer. </description> </method> <method name="_font_set_glyph_advance" qualifiers="virtual"> @@ -630,6 +839,8 @@ <param index="2" name="glyph" type="int" /> <param index="3" name="advance" type="Vector2" /> <description> + [b]Required.[/b] + Sets glyph advance (offset of the next glyph). </description> </method> <method name="_font_set_glyph_offset" qualifiers="virtual"> @@ -639,6 +850,8 @@ <param index="2" name="glyph" type="int" /> <param index="3" name="offset" type="Vector2" /> <description> + [b]Required.[/b] + Sets glyph offset from the baseline. </description> </method> <method name="_font_set_glyph_size" qualifiers="virtual"> @@ -648,6 +861,8 @@ <param index="2" name="glyph" type="int" /> <param index="3" name="gl_size" type="Vector2" /> <description> + [b]Required.[/b] + Sets size of the glyph. </description> </method> <method name="_font_set_glyph_texture_idx" qualifiers="virtual"> @@ -657,6 +872,8 @@ <param index="2" name="glyph" type="int" /> <param index="3" name="texture_idx" type="int" /> <description> + [b]Required.[/b] + Sets index of the cache texture containing the glyph. </description> </method> <method name="_font_set_glyph_uv_rect" qualifiers="virtual"> @@ -666,6 +883,8 @@ <param index="2" name="glyph" type="int" /> <param index="3" name="uv_rect" type="Rect2" /> <description> + [b]Required.[/b] + Sets rectangle in the cache texture containing the glyph. </description> </method> <method name="_font_set_hinting" qualifiers="virtual"> @@ -673,6 +892,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="hinting" type="int" enum="TextServer.Hinting" /> <description> + [b]Optional.[/b] + Sets font hinting mode. Used by dynamic fonts only. </description> </method> <method name="_font_set_kerning" qualifiers="virtual"> @@ -682,6 +903,8 @@ <param index="2" name="glyph_pair" type="Vector2i" /> <param index="3" name="kerning" type="Vector2" /> <description> + [b]Optional.[/b] + Sets kerning for the pair of glyphs. </description> </method> <method name="_font_set_language_support_override" qualifiers="virtual"> @@ -690,6 +913,8 @@ <param index="1" name="language" type="String" /> <param index="2" name="supported" type="bool" /> <description> + [b]Optional.[/b] + Adds override for [method _font_is_language_supported]. </description> </method> <method name="_font_set_msdf_pixel_range" qualifiers="virtual"> @@ -697,6 +922,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="msdf_pixel_range" type="int" /> <description> + [b]Optional.[/b] + Sets the width of the range around the shape between the minimum and maximum representable signed distance. </description> </method> <method name="_font_set_msdf_size" qualifiers="virtual"> @@ -704,6 +931,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="msdf_size" type="int" /> <description> + [b]Optional.[/b] + Sets source font size used to generate MSDF textures. </description> </method> <method name="_font_set_multichannel_signed_distance_field" qualifiers="virtual"> @@ -711,6 +940,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="msdf" type="bool" /> <description> + [b]Optional.[/b] + If set to [code]true[/code], glyphs of all sizes are rendered using single multichannel signed distance field generated from the dynamic font vector data. MSDF rendering allows displaying the font at any scaling factor without blurriness, and without incurring a CPU cost when the font size changes (since the font no longer needs to be rasterized on the CPU). As a downside, font hinting is not available with MSDF. The lack of font hinting may result in less crisp and less readable fonts at small sizes. </description> </method> <method name="_font_set_name" qualifiers="virtual"> @@ -718,6 +949,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="name" type="String" /> <description> + [b]Optional.[/b] + Sets the font family name. </description> </method> <method name="_font_set_opentype_feature_overrides" qualifiers="virtual"> @@ -725,6 +958,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="overrides" type="Dictionary" /> <description> + [b]Optional.[/b] + Sets font OpenType feature set override. </description> </method> <method name="_font_set_oversampling" qualifiers="virtual"> @@ -732,6 +967,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="oversampling" type="float" /> <description> + [b]Optional.[/b] + Sets font oversampling factor, if set to [code]0.0[/code] global oversampling factor is used instead. Used by dynamic fonts only. </description> </method> <method name="_font_set_scale" qualifiers="virtual"> @@ -740,6 +977,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="scale" type="float" /> <description> + [b]Required.[/b] + Sets scaling factor of the color bitmap font. </description> </method> <method name="_font_set_script_support_override" qualifiers="virtual"> @@ -748,6 +987,8 @@ <param index="1" name="script" type="String" /> <param index="2" name="supported" type="bool" /> <description> + [b]Optional.[/b] + Adds override for [method _font_is_script_supported]. </description> </method> <method name="_font_set_spacing" qualifiers="virtual"> @@ -756,6 +997,8 @@ <param index="1" name="spacing" type="int" enum="TextServer.SpacingType" /> <param index="2" name="value" type="int" /> <description> + [b]Optional.[/b] + Sets the spacing for [param spacing] (see [enum TextServer.SpacingType]) to [param value] in pixels (not relative to the font size). </description> </method> <method name="_font_set_stretch" qualifiers="virtual"> @@ -763,6 +1006,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="stretch" type="int" /> <description> + [b]Optional.[/b] + Sets font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. </description> </method> <method name="_font_set_style" qualifiers="virtual"> @@ -770,6 +1015,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="style" type="int" enum="TextServer.FontStyle" is_bitfield="true" /> <description> + [b]Optional.[/b] + Sets the font style flags, see [enum TextServer.FontStyle]. </description> </method> <method name="_font_set_style_name" qualifiers="virtual"> @@ -777,6 +1024,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="name_style" type="String" /> <description> + [b]Optional.[/b] + Sets the font style name. </description> </method> <method name="_font_set_subpixel_positioning" qualifiers="virtual"> @@ -784,6 +1033,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="subpixel_positioning" type="int" enum="TextServer.SubpixelPositioning" /> <description> + [b]Optional.[/b] + Sets font subpixel glyph positioning mode. </description> </method> <method name="_font_set_texture_image" qualifiers="virtual"> @@ -793,6 +1044,8 @@ <param index="2" name="texture_index" type="int" /> <param index="3" name="image" type="Image" /> <description> + [b]Required.[/b] + Sets font cache texture image data. </description> </method> <method name="_font_set_texture_offsets" qualifiers="virtual"> @@ -802,6 +1055,8 @@ <param index="2" name="texture_index" type="int" /> <param index="3" name="offset" type="PackedInt32Array" /> <description> + [b]Optional.[/b] + Sets array containing glyph packing data. </description> </method> <method name="_font_set_transform" qualifiers="virtual"> @@ -809,6 +1064,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="transform" type="Transform2D" /> <description> + [b]Optional.[/b] + Sets 2D transform, applied to the font outlines, can be used for slanting, flipping, and rotating glyphs. </description> </method> <method name="_font_set_underline_position" qualifiers="virtual"> @@ -817,6 +1074,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="underline_position" type="float" /> <description> + [b]Required.[/b] + Sets pixel offset of the underline below the baseline. </description> </method> <method name="_font_set_underline_thickness" qualifiers="virtual"> @@ -825,6 +1084,8 @@ <param index="1" name="size" type="int" /> <param index="2" name="underline_thickness" type="float" /> <description> + [b]Required.[/b] + Sets thickness of the underline in pixels. </description> </method> <method name="_font_set_variation_coordinates" qualifiers="virtual"> @@ -832,6 +1093,8 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="variation_coordinates" type="Dictionary" /> <description> + [b]Optional.[/b] + Sets variation coordinates for the specified font cache entry. </description> </method> <method name="_font_set_weight" qualifiers="virtual"> @@ -839,36 +1102,48 @@ <param index="0" name="font_rid" type="RID" /> <param index="1" name="weight" type="int" /> <description> + [b]Optional.[/b] + Sets weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. </description> </method> <method name="_font_supported_feature_list" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns the dictionary of the supported OpenType features. </description> </method> <method name="_font_supported_variation_list" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> <description> + [b]Optional.[/b] + Returns the dictionary of the supported OpenType variation coordinates. </description> </method> <method name="_format_number" qualifiers="virtual const"> <return type="String" /> - <param index="0" name="string" type="String" /> + <param index="0" name="number" type="String" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Converts a number from the Western Arabic (0..9) to the numeral systems used in [param language]. </description> </method> <method name="_free_rid" qualifiers="virtual"> <return type="void" /> <param index="0" name="rid" type="RID" /> <description> + [b]Required.[/b] + Frees an object created by this [TextServer]. </description> </method> <method name="_get_features" qualifiers="virtual const"> <return type="int" /> <description> + [b]Required.[/b] + Returns text server features, see [enum TextServer.Feature]. </description> </method> <method name="_get_hex_code_box_size" qualifiers="virtual const"> @@ -876,33 +1151,45 @@ <param index="0" name="size" type="int" /> <param index="1" name="index" type="int" /> <description> + [b]Optional.[/b] + Returns size of the replacement character (box with character hexadecimal code that is drawn in place of invalid characters). </description> </method> <method name="_get_name" qualifiers="virtual const"> <return type="String" /> <description> + [b]Required.[/b] + Returns the name of the server interface. </description> </method> <method name="_get_support_data_filename" qualifiers="virtual const"> <return type="String" /> <description> + [b]Optional.[/b] + Returns default TextServer database (e.g. ICU break iterators and dictionaries) filename. </description> </method> <method name="_get_support_data_info" qualifiers="virtual const"> <return type="String" /> <description> + [b]Optional.[/b] + Returns TextServer database (e.g. ICU break iterators and dictionaries) description. </description> </method> <method name="_has" qualifiers="virtual"> <return type="bool" /> <param index="0" name="rid" type="RID" /> <description> + [b]Required.[/b] + Returns [code]true[/code] if [param rid] is valid resource owned by this text server. </description> </method> <method name="_has_feature" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="feature" type="int" enum="TextServer.Feature" /> <description> + [b]Required.[/b] + Returns [code]true[/code] if the server supports a feature. </description> </method> <method name="_is_confusable" qualifiers="virtual const"> @@ -910,37 +1197,49 @@ <param index="0" name="string" type="String" /> <param index="1" name="dict" type="PackedStringArray" /> <description> + [b]Optional.[/b] + Returns index of the first string in [param dict] which is visually confusable with the [param string], or [code]-1[/code] if none is found. </description> </method> <method name="_is_locale_right_to_left" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="locale" type="String" /> <description> + [b]Required.[/b] + Returns [code]true[/code] if locale is right-to-left. </description> </method> <method name="_is_valid_identifier" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="string" type="String" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if [param string] is a valid identifier. </description> </method> <method name="_load_support_data" qualifiers="virtual"> <return type="bool" /> <param index="0" name="filename" type="String" /> <description> + [b]Optional.[/b] + Loads optional TextServer database (e.g. ICU break iterators and dictionaries). </description> </method> <method name="_name_to_tag" qualifiers="virtual const"> <return type="int" /> <param index="0" name="name" type="String" /> <description> + [b]Optional.[/b] + Converts readable feature, variation, script, or language name to OpenType tag. </description> </method> <method name="_parse_number" qualifiers="virtual const"> <return type="String" /> - <param index="0" name="string" type="String" /> + <param index="0" name="number" type="String" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Converts [param number] from the numeral systems used in [param language] to Western Arabic (0..9). </description> </method> <method name="_parse_structured_text" qualifiers="virtual const"> @@ -949,24 +1248,32 @@ <param index="1" name="args" type="Array" /> <param index="2" name="text" type="String" /> <description> + [b]Optional.[/b] + Default implementation of the BiDi algorithm override function. See [enum TextServer.StructuredTextParser] for more info. </description> </method> <method name="_percent_sign" qualifiers="virtual const"> <return type="String" /> <param index="0" name="language" type="String" /> <description> + [b]Optional.[/b] + Returns percent sign used in the [param language]. </description> </method> <method name="_save_support_data" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="filename" type="String" /> <description> + [b]Optional.[/b] + Saves optional TextServer database (e.g. ICU break iterators and dictionaries) to the file. </description> </method> <method name="_shaped_get_span_count" qualifiers="virtual const"> <return type="int" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns number of text spans added using [method _shaped_text_add_string] or [method _shaped_text_add_object]. </description> </method> <method name="_shaped_get_span_meta" qualifiers="virtual const"> @@ -974,6 +1281,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="index" type="int" /> <description> + [b]Required.[/b] + Returns text span metadata. </description> </method> <method name="_shaped_set_span_update_font" qualifiers="virtual"> @@ -984,6 +1293,8 @@ <param index="3" name="size" type="int" /> <param index="4" name="opentype_features" type="Dictionary" /> <description> + [b]Required.[/b] + Changes text span font, font size, and OpenType features, without changing the text. </description> </method> <method name="_shaped_text_add_object" qualifiers="virtual"> @@ -995,6 +1306,8 @@ <param index="4" name="length" type="int" /> <param index="5" name="baseline" type="float" /> <description> + [b]Required.[/b] + Adds inline object to the text buffer, [param key] must be unique. In the text, object is represented as [param length] object replacement characters. </description> </method> <method name="_shaped_text_add_string" qualifiers="virtual"> @@ -1007,12 +1320,16 @@ <param index="5" name="language" type="String" /> <param index="6" name="meta" type="Variant" /> <description> + [b]Required.[/b] + Adds text span and font to draw it to the text buffer. </description> </method> <method name="_shaped_text_clear" qualifiers="virtual"> <return type="void" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Clears text buffer (removes text and inline objects). </description> </method> <method name="_shaped_text_closest_character_pos" qualifiers="virtual const"> @@ -1020,6 +1337,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="pos" type="int" /> <description> + [b]Optional.[/b] + Returns composite character position closest to the [param pos]. </description> </method> <method name="_shaped_text_draw" qualifiers="virtual const"> @@ -1031,6 +1350,8 @@ <param index="4" name="clip_r" type="float" /> <param index="5" name="color" type="Color" /> <description> + [b]Optional.[/b] + Draw shaped text into a canvas item at a given position, with [param color]. [param pos] specifies the leftmost point of the baseline (for horizontal layout) or topmost point of the baseline (for vertical layout). </description> </method> <method name="_shaped_text_draw_outline" qualifiers="virtual const"> @@ -1043,6 +1364,8 @@ <param index="5" name="outline_size" type="int" /> <param index="6" name="color" type="Color" /> <description> + [b]Optional.[/b] + Draw the outline of the shaped text into a canvas item at a given position, with [param color]. [param pos] specifies the leftmost point of the baseline (for horizontal layout) or topmost point of the baseline (for vertical layout). </description> </method> <method name="_shaped_text_fit_to_width" qualifiers="virtual"> @@ -1051,12 +1374,16 @@ <param index="1" name="width" type="float" /> <param index="2" name="justification_flags" type="int" enum="TextServer.JustificationFlag" is_bitfield="true" /> <description> + [b]Optional.[/b] + Adjusts text width to fit to specified width, returns new text width. </description> </method> <method name="_shaped_text_get_ascent" qualifiers="virtual const"> <return type="float" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns the text ascent (number of pixels above the baseline for horizontal layout or to the left of baseline for vertical). </description> </method> <method name="_shaped_text_get_carets" qualifiers="virtual const"> @@ -1065,30 +1392,48 @@ <param index="1" name="position" type="int" /> <param index="2" name="caret" type="CaretInfo*" /> <description> + [b]Optional.[/b] + Returns shapes of the carets corresponding to the character offset [param position] in the text. Returned caret shape is 1 pixel wide rectangle. </description> </method> <method name="_shaped_text_get_character_breaks" qualifiers="virtual const"> <return type="PackedInt32Array" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Returns array of the composite character boundaries. + </description> + </method> + <method name="_shaped_text_get_custom_ellipsis" qualifiers="virtual const"> + <return type="int" /> + <param index="0" name="shaped" type="RID" /> + <description> + [b]Optional.[/b] + Returns ellipsis character used for text clipping. </description> </method> <method name="_shaped_text_get_custom_punctuation" qualifiers="virtual const"> <return type="String" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Returns custom punctuation character list, used for word breaking. If set to empty string, server defaults are used. </description> </method> <method name="_shaped_text_get_descent" qualifiers="virtual const"> <return type="float" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns the text descent (number of pixels below the baseline for horizontal layout or to the right of baseline for vertical). </description> </method> <method name="_shaped_text_get_direction" qualifiers="virtual const"> <return type="int" enum="TextServer.Direction" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Returns direction of the text. </description> </method> <method name="_shaped_text_get_dominant_direction_in_range" qualifiers="virtual const"> @@ -1097,36 +1442,48 @@ <param index="1" name="start" type="int" /> <param index="2" name="end" type="int" /> <description> + [b]Optional.[/b] + Returns dominant direction of in the range of text. </description> </method> <method name="_shaped_text_get_ellipsis_glyph_count" qualifiers="virtual const"> <return type="int" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns number of glyphs in the ellipsis. </description> </method> <method name="_shaped_text_get_ellipsis_glyphs" qualifiers="virtual const"> <return type="const Glyph*" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns array of the glyphs in the ellipsis. </description> </method> <method name="_shaped_text_get_ellipsis_pos" qualifiers="virtual const"> <return type="int" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns position of the ellipsis. </description> </method> <method name="_shaped_text_get_glyph_count" qualifiers="virtual const"> <return type="int" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns number of glyphs in the buffer. </description> </method> <method name="_shaped_text_get_glyphs" qualifiers="virtual const"> <return type="const Glyph*" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns an array of glyphs in the visual order. </description> </method> <method name="_shaped_text_get_grapheme_bounds" qualifiers="virtual const"> @@ -1134,12 +1491,16 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="pos" type="int" /> <description> + [b]Optional.[/b] + Returns composite character's bounds as offsets from the start of the line. </description> </method> <method name="_shaped_text_get_inferred_direction" qualifiers="virtual const"> <return type="int" enum="TextServer.Direction" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Returns direction of the text, inferred by the BiDi algorithm. </description> </method> <method name="_shaped_text_get_line_breaks" qualifiers="virtual const"> @@ -1149,6 +1510,8 @@ <param index="2" name="start" type="int" /> <param index="3" name="break_flags" type="int" enum="TextServer.LineBreakFlag" is_bitfield="true" /> <description> + [b]Optional.[/b] + Breaks text to the lines and returns character ranges for each line. </description> </method> <method name="_shaped_text_get_line_breaks_adv" qualifiers="virtual const"> @@ -1159,6 +1522,26 @@ <param index="3" name="once" type="bool" /> <param index="4" name="break_flags" type="int" enum="TextServer.LineBreakFlag" is_bitfield="true" /> <description> + [b]Optional.[/b] + Breaks text to the lines and columns. Returns character ranges for each segment. + </description> + </method> + <method name="_shaped_text_get_object_glyph" qualifiers="virtual const"> + <return type="int" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="key" type="Variant" /> + <description> + [b]Required.[/b] + Returns the glyph index of the inline object. + </description> + </method> + <method name="_shaped_text_get_object_range" qualifiers="virtual const"> + <return type="Vector2i" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="key" type="Variant" /> + <description> + [b]Required.[/b] + Returns the character range of the inline object. </description> </method> <method name="_shaped_text_get_object_rect" qualifiers="virtual const"> @@ -1166,42 +1549,56 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="key" type="Variant" /> <description> + [b]Required.[/b] + Returns bounding rectangle of the inline object. </description> </method> <method name="_shaped_text_get_objects" qualifiers="virtual const"> <return type="Array" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns array of inline objects. </description> </method> <method name="_shaped_text_get_orientation" qualifiers="virtual const"> <return type="int" enum="TextServer.Orientation" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Returns text orientation. </description> </method> <method name="_shaped_text_get_parent" qualifiers="virtual const"> <return type="RID" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns the parent buffer from which the substring originates. </description> </method> <method name="_shaped_text_get_preserve_control" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if text buffer is configured to display control characters. </description> </method> <method name="_shaped_text_get_preserve_invalid" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if text buffer is configured to display hexadecimal codes in place of invalid characters. </description> </method> <method name="_shaped_text_get_range" qualifiers="virtual const"> <return type="Vector2i" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns substring buffer character range in the parent buffer. </description> </method> <method name="_shaped_text_get_selection" qualifiers="virtual const"> @@ -1210,12 +1607,16 @@ <param index="1" name="start" type="int" /> <param index="2" name="end" type="int" /> <description> + [b]Optional.[/b] + Returns selection rectangles for the specified character range. </description> </method> <method name="_shaped_text_get_size" qualifiers="virtual const"> <return type="Vector2" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns size of the text. </description> </method> <method name="_shaped_text_get_spacing" qualifiers="virtual const"> @@ -1223,30 +1624,40 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="spacing" type="int" enum="TextServer.SpacingType" /> <description> + [b]Optional.[/b] + Returns extra spacing added between glyphs or lines in pixels. </description> </method> <method name="_shaped_text_get_trim_pos" qualifiers="virtual const"> <return type="int" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns the position of the overrun trim. </description> </method> <method name="_shaped_text_get_underline_position" qualifiers="virtual const"> <return type="float" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns pixel offset of the underline below the baseline. </description> </method> <method name="_shaped_text_get_underline_thickness" qualifiers="virtual const"> <return type="float" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns thickness of the underline. </description> </method> <method name="_shaped_text_get_width" qualifiers="virtual const"> <return type="float" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns width (for horizontal layout) or height (for vertical) of the text. </description> </method> <method name="_shaped_text_get_word_breaks" qualifiers="virtual const"> @@ -1254,6 +1665,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="grapheme_flags" type="int" enum="TextServer.GraphemeFlag" is_bitfield="true" /> <description> + [b]Optional.[/b] + Breaks text into words and returns array of character ranges. Use [param grapheme_flags] to set what characters are used for breaking (see [enum TextServer.GraphemeFlag]). </description> </method> <method name="_shaped_text_hit_test_grapheme" qualifiers="virtual const"> @@ -1261,6 +1674,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="coord" type="float" /> <description> + [b]Optional.[/b] + Returns grapheme index at the specified pixel offset at the baseline, or [code]-1[/code] if none is found. </description> </method> <method name="_shaped_text_hit_test_position" qualifiers="virtual const"> @@ -1268,12 +1683,16 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="coord" type="float" /> <description> + [b]Optional.[/b] + Returns caret character offset at the specified pixel offset at the baseline. This function always returns a valid position. </description> </method> <method name="_shaped_text_is_ready" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns [code]true[/code] if buffer is successfully shaped. </description> </method> <method name="_shaped_text_next_character_pos" qualifiers="virtual const"> @@ -1281,6 +1700,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="pos" type="int" /> <description> + [b]Optional.[/b] + Returns composite character end position closest to the [param pos]. </description> </method> <method name="_shaped_text_next_grapheme_pos" qualifiers="virtual const"> @@ -1288,6 +1709,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="pos" type="int" /> <description> + [b]Optional.[/b] + Returns grapheme end position closest to the [param pos]. </description> </method> <method name="_shaped_text_overrun_trim_to_width" qualifiers="virtual"> @@ -1296,6 +1719,8 @@ <param index="1" name="width" type="float" /> <param index="2" name="trim_flags" type="int" enum="TextServer.TextOverrunFlag" is_bitfield="true" /> <description> + [b]Optional.[/b] + Trims text if it exceeds the given width. </description> </method> <method name="_shaped_text_prev_character_pos" qualifiers="virtual const"> @@ -1303,6 +1728,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="pos" type="int" /> <description> + [b]Optional.[/b] + Returns composite character start position closest to the [param pos]. </description> </method> <method name="_shaped_text_prev_grapheme_pos" qualifiers="virtual const"> @@ -1310,6 +1737,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="pos" type="int" /> <description> + [b]Optional.[/b] + Returns grapheme start position closest to the [param pos]. </description> </method> <method name="_shaped_text_resize_object" qualifiers="virtual"> @@ -1320,6 +1749,8 @@ <param index="3" name="inline_align" type="int" enum="InlineAlignment" /> <param index="4" name="baseline" type="float" /> <description> + [b]Required.[/b] + Sets new size and alignment of embedded object. </description> </method> <method name="_shaped_text_set_bidi_override" qualifiers="virtual"> @@ -1327,6 +1758,17 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="override" type="Array" /> <description> + [b]Optional.[/b] + Overrides BiDi for the structured text. + </description> + </method> + <method name="_shaped_text_set_custom_ellipsis" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="char" type="int" /> + <description> + [b]Optional.[/b] + Sets ellipsis character used for text clipping. </description> </method> <method name="_shaped_text_set_custom_punctuation" qualifiers="virtual"> @@ -1334,6 +1776,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="punct" type="String" /> <description> + [b]Optional.[/b] + Sets custom punctuation character list, used for word breaking. If set to empty string, server defaults are used. </description> </method> <method name="_shaped_text_set_direction" qualifiers="virtual"> @@ -1341,6 +1785,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="direction" type="int" enum="TextServer.Direction" /> <description> + [b]Optional.[/b] + Sets desired text direction. If set to [constant TextServer.DIRECTION_AUTO], direction will be detected based on the buffer contents and current locale. </description> </method> <method name="_shaped_text_set_orientation" qualifiers="virtual"> @@ -1348,6 +1794,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="orientation" type="int" enum="TextServer.Orientation" /> <description> + [b]Optional.[/b] + Sets desired text orientation. </description> </method> <method name="_shaped_text_set_preserve_control" qualifiers="virtual"> @@ -1355,6 +1803,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="enabled" type="bool" /> <description> + [b]Optional.[/b] + If set to [code]true[/code] text buffer will display control characters. </description> </method> <method name="_shaped_text_set_preserve_invalid" qualifiers="virtual"> @@ -1362,6 +1812,8 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="enabled" type="bool" /> <description> + [b]Optional.[/b] + If set to [code]true[/code] text buffer will display invalid characters as hexadecimal codes, otherwise nothing is displayed. </description> </method> <method name="_shaped_text_set_spacing" qualifiers="virtual"> @@ -1370,18 +1822,24 @@ <param index="1" name="spacing" type="int" enum="TextServer.SpacingType" /> <param index="2" name="value" type="int" /> <description> + [b]Optional.[/b] + Sets extra spacing added between glyphs or lines in pixels. </description> </method> <method name="_shaped_text_shape" qualifiers="virtual"> <return type="bool" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Shapes buffer if it's not shaped. Returns [code]true[/code] if the string is shaped successfully. </description> </method> <method name="_shaped_text_sort_logical" qualifiers="virtual"> <return type="const Glyph*" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Required.[/b] + Returns text glyphs in the logical order. </description> </method> <method name="_shaped_text_substr" qualifiers="virtual const"> @@ -1390,6 +1848,8 @@ <param index="1" name="start" type="int" /> <param index="2" name="length" type="int" /> <description> + [b]Required.[/b] + Returns text buffer for the substring of the text in the [param shaped] text buffer (including inline objects). </description> </method> <method name="_shaped_text_tab_align" qualifiers="virtual"> @@ -1397,24 +1857,32 @@ <param index="0" name="shaped" type="RID" /> <param index="1" name="tab_stops" type="PackedFloat32Array" /> <description> + [b]Optional.[/b] + Aligns shaped text to the given tab-stops. </description> </method> <method name="_shaped_text_update_breaks" qualifiers="virtual"> <return type="bool" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Updates break points in the shaped text. This method is called by default implementation of text breaking functions. </description> </method> <method name="_shaped_text_update_justification_ops" qualifiers="virtual"> <return type="bool" /> <param index="0" name="shaped" type="RID" /> <description> + [b]Optional.[/b] + Updates justification points in the shaped text. This method is called by default implementation of text justification functions. </description> </method> <method name="_spoof_check" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="string" type="String" /> <description> + [b]Optional.[/b] + Returns [code]true[/code] if [param string] is likely to be an attempt at confusing the reader. </description> </method> <method name="_string_get_character_breaks" qualifiers="virtual const"> @@ -1422,6 +1890,8 @@ <param index="0" name="string" type="String" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Returns array of the composite character boundaries. </description> </method> <method name="_string_get_word_breaks" qualifiers="virtual const"> @@ -1430,6 +1900,8 @@ <param index="1" name="language" type="String" /> <param index="2" name="chars_per_line" type="int" /> <description> + [b]Optional.[/b] + Returns an array of the word break boundaries. Elements in the returned array are the offsets of the start and end of words. Therefore the length of the array is always even. </description> </method> <method name="_string_to_lower" qualifiers="virtual const"> @@ -1437,6 +1909,17 @@ <param index="0" name="string" type="String" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Returns the string converted to lowercase. + </description> + </method> + <method name="_string_to_title" qualifiers="virtual const"> + <return type="String" /> + <param index="0" name="string" type="String" /> + <param index="1" name="language" type="String" /> + <description> + [b]Optional.[/b] + Returns the string converted to title case. </description> </method> <method name="_string_to_upper" qualifiers="virtual const"> @@ -1444,18 +1927,24 @@ <param index="0" name="string" type="String" /> <param index="1" name="language" type="String" /> <description> + [b]Optional.[/b] + Returns the string converted to uppercase. </description> </method> <method name="_strip_diacritics" qualifiers="virtual const"> <return type="String" /> <param index="0" name="string" type="String" /> <description> + [b]Optional.[/b] + Strips diacritics from the string. </description> </method> <method name="_tag_to_name" qualifiers="virtual const"> <return type="String" /> <param index="0" name="tag" type="int" /> <description> + [b]Optional.[/b] + Converts OpenType tag to readable feature, variation, script, or language name. </description> </method> </methods> diff --git a/doc/classes/Texture2D.xml b/doc/classes/Texture2D.xml index 087f3a70f8..7254a92e36 100644 --- a/doc/classes/Texture2D.xml +++ b/doc/classes/Texture2D.xml @@ -123,6 +123,7 @@ <return type="Image" /> <description> Returns an [Image] that is a copy of data from this [Texture2D] (a new [Image] is created each time). [Image]s can be accessed and manipulated directly. + [b]Note:[/b] This will return [code]null[/code] if this [Texture2D] is invalid. [b]Note:[/b] This will fetch the texture data from the GPU, which might cause performance problems when overused. </description> </method> diff --git a/doc/classes/Texture2DRD.xml b/doc/classes/Texture2DRD.xml index b935a7763b..fe3a8a3213 100644 --- a/doc/classes/Texture2DRD.xml +++ b/doc/classes/Texture2DRD.xml @@ -10,7 +10,7 @@ </tutorials> <members> <member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene" overrides="Resource" default="false" /> - <member name="texture_rd_rid" type="RID" setter="set_texture_rd_rid" getter="get_texture_rd_rid" default="RID()"> + <member name="texture_rd_rid" type="RID" setter="set_texture_rd_rid" getter="get_texture_rd_rid"> The RID of the texture object created on the [RenderingDevice]. </member> </members> diff --git a/doc/classes/Texture3D.xml b/doc/classes/Texture3D.xml index 6f054a8e0d..2b1bc026c2 100644 --- a/doc/classes/Texture3D.xml +++ b/doc/classes/Texture3D.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Texture3D" inherits="Texture" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Base class for 3-dimensionnal textures. + Base class for 3-dimensional textures. </brief_description> <description> Base class for [ImageTexture3D] and [CompressedTexture3D]. Cannot be used directly, but contains all the functions necessary for accessing the derived resource types. [Texture3D] is the base class for all 3-dimensional texture types. See also [TextureLayered]. diff --git a/doc/classes/Texture3DRD.xml b/doc/classes/Texture3DRD.xml index f9d72b7a0f..38cd454bec 100644 --- a/doc/classes/Texture3DRD.xml +++ b/doc/classes/Texture3DRD.xml @@ -9,7 +9,7 @@ <tutorials> </tutorials> <members> - <member name="texture_rd_rid" type="RID" setter="set_texture_rd_rid" getter="get_texture_rd_rid" default="RID()"> + <member name="texture_rd_rid" type="RID" setter="set_texture_rd_rid" getter="get_texture_rd_rid"> The RID of the texture object created on the [RenderingDevice]. </member> </members> diff --git a/doc/classes/TextureLayeredRD.xml b/doc/classes/TextureLayeredRD.xml index 65f2d87624..c3de7f6913 100644 --- a/doc/classes/TextureLayeredRD.xml +++ b/doc/classes/TextureLayeredRD.xml @@ -9,7 +9,7 @@ <tutorials> </tutorials> <members> - <member name="texture_rd_rid" type="RID" setter="set_texture_rd_rid" getter="get_texture_rd_rid" default="RID()"> + <member name="texture_rd_rid" type="RID" setter="set_texture_rd_rid" getter="get_texture_rd_rid"> The RID of the texture object created on the [RenderingDevice]. </member> </members> diff --git a/doc/classes/TextureProgressBar.xml b/doc/classes/TextureProgressBar.xml index 0c1e9adf71..d3e334ef55 100644 --- a/doc/classes/TextureProgressBar.xml +++ b/doc/classes/TextureProgressBar.xml @@ -34,28 +34,28 @@ If [code]true[/code], Godot treats the bar's textures like in [NinePatchRect]. Use the [code]stretch_margin_*[/code] properties like [member stretch_margin_bottom] to set up the nine patch's 3×3 grid. When using a radial [member fill_mode], this setting will enable stretching. </member> <member name="radial_center_offset" type="Vector2" setter="set_radial_center_offset" getter="get_radial_center_offset" default="Vector2(0, 0)"> - Offsets [member texture_progress] if [member fill_mode] is [constant FILL_CLOCKWISE] or [constant FILL_COUNTER_CLOCKWISE]. + Offsets [member texture_progress] if [member fill_mode] is [constant FILL_CLOCKWISE], [constant FILL_COUNTER_CLOCKWISE], or [constant FILL_CLOCKWISE_AND_COUNTER_CLOCKWISE]. </member> <member name="radial_fill_degrees" type="float" setter="set_fill_degrees" getter="get_fill_degrees" default="360.0"> - Upper limit for the fill of [member texture_progress] if [member fill_mode] is [constant FILL_CLOCKWISE] or [constant FILL_COUNTER_CLOCKWISE]. When the node's [code]value[/code] is equal to its [code]max_value[/code], the texture fills up to this angle. + Upper limit for the fill of [member texture_progress] if [member fill_mode] is [constant FILL_CLOCKWISE], [constant FILL_COUNTER_CLOCKWISE], or [constant FILL_CLOCKWISE_AND_COUNTER_CLOCKWISE]. When the node's [code]value[/code] is equal to its [code]max_value[/code], the texture fills up to this angle. See [member Range.value], [member Range.max_value]. </member> <member name="radial_initial_angle" type="float" setter="set_radial_initial_angle" getter="get_radial_initial_angle" default="0.0"> - Starting angle for the fill of [member texture_progress] if [member fill_mode] is [constant FILL_CLOCKWISE] or [constant FILL_COUNTER_CLOCKWISE]. When the node's [code]value[/code] is equal to its [code]min_value[/code], the texture doesn't show up at all. When the [code]value[/code] increases, the texture fills and tends towards [member radial_fill_degrees]. + Starting angle for the fill of [member texture_progress] if [member fill_mode] is [constant FILL_CLOCKWISE], [constant FILL_COUNTER_CLOCKWISE], or [constant FILL_CLOCKWISE_AND_COUNTER_CLOCKWISE]. When the node's [code]value[/code] is equal to its [code]min_value[/code], the texture doesn't show up at all. When the [code]value[/code] increases, the texture fills and tends towards [member radial_fill_degrees]. </member> <member name="size_flags_vertical" type="int" setter="set_v_size_flags" getter="get_v_size_flags" overrides="Control" enum="Control.SizeFlags" is_bitfield="true" default="1" /> <member name="step" type="float" setter="set_step" getter="get_step" overrides="Range" default="1.0" /> <member name="stretch_margin_bottom" type="int" setter="set_stretch_margin" getter="get_stretch_margin" default="0"> - The height of the 9-patch's bottom row. A margin of 16 means the 9-slice's bottom corners and side will have a height of 16 pixels. You can set all 4 margin values individually to create panels with non-uniform borders. + The height of the 9-patch's bottom row. A margin of 16 means the 9-slice's bottom corners and side will have a height of 16 pixels. You can set all 4 margin values individually to create panels with non-uniform borders. Only effective if [member nine_patch_stretch] is [code]true[/code]. </member> <member name="stretch_margin_left" type="int" setter="set_stretch_margin" getter="get_stretch_margin" default="0"> - The width of the 9-patch's left column. + The width of the 9-patch's left column. Only effective if [member nine_patch_stretch] is [code]true[/code]. </member> <member name="stretch_margin_right" type="int" setter="set_stretch_margin" getter="get_stretch_margin" default="0"> - The width of the 9-patch's right column. + The width of the 9-patch's right column. Only effective if [member nine_patch_stretch] is [code]true[/code]. </member> <member name="stretch_margin_top" type="int" setter="set_stretch_margin" getter="get_stretch_margin" default="0"> - The height of the 9-patch's top row. + The height of the 9-patch's top row. Only effective if [member nine_patch_stretch] is [code]true[/code]. </member> <member name="texture_over" type="Texture2D" setter="set_over_texture" getter="get_over_texture"> [Texture2D] that draws over the progress bar. Use it to add highlights or an upper-frame that hides part of [member texture_progress]. @@ -70,13 +70,13 @@ <member name="texture_under" type="Texture2D" setter="set_under_texture" getter="get_under_texture"> [Texture2D] that draws under the progress bar. The bar's background. </member> - <member name="tint_over" type="Color" setter="set_tint_over" getter="get_tint_over" default="Color(1, 1, 1, 1)"> + <member name="tint_over" type="Color" setter="set_tint_over" getter="get_tint_over" default="Color(1, 1, 1, 1)" keywords="color, colour"> Multiplies the color of the bar's [member texture_over] texture. The effect is similar to [member CanvasItem.modulate], except it only affects this specific texture instead of the entire node. </member> - <member name="tint_progress" type="Color" setter="set_tint_progress" getter="get_tint_progress" default="Color(1, 1, 1, 1)"> + <member name="tint_progress" type="Color" setter="set_tint_progress" getter="get_tint_progress" default="Color(1, 1, 1, 1)" keywords="color, colour"> Multiplies the color of the bar's [member texture_progress] texture. </member> - <member name="tint_under" type="Color" setter="set_tint_under" getter="get_tint_under" default="Color(1, 1, 1, 1)"> + <member name="tint_under" type="Color" setter="set_tint_under" getter="get_tint_under" default="Color(1, 1, 1, 1)" keywords="color, colour"> Multiplies the color of the bar's [member texture_under] texture. </member> </members> diff --git a/doc/classes/TextureRect.xml b/doc/classes/TextureRect.xml index d5f60839b9..d18c4a1eee 100644 --- a/doc/classes/TextureRect.xml +++ b/doc/classes/TextureRect.xml @@ -10,9 +10,8 @@ <link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/676</link> </tutorials> <members> - <member name="expand_mode" type="int" setter="set_expand_mode" getter="get_expand_mode" enum="TextureRect.ExpandMode" default="0" is_experimental="true"> + <member name="expand_mode" type="int" setter="set_expand_mode" getter="get_expand_mode" enum="TextureRect.ExpandMode" default="0" experimental="Using [constant EXPAND_FIT_WIDTH], [constant EXPAND_FIT_WIDTH_PROPORTIONAL], [constant EXPAND_FIT_HEIGHT], or [constant EXPAND_FIT_HEIGHT_PROPORTIONAL] may result in unstable behavior in some [Container] controls. This behavior may be re-evaluated and changed in the future."> Defines how minimum size is determined based on the texture's size. See [enum ExpandMode] for options. - [b]Note:[/b] Using [constant EXPAND_FIT_WIDTH], [constant EXPAND_FIT_WIDTH_PROPORTIONAL], [constant EXPAND_FIT_HEIGHT] or [constant EXPAND_FIT_HEIGHT_PROPORTIONAL] may result in unstable behavior in some containers. This functionality is being re-evaluated and will change in the future. </member> <member name="flip_h" type="bool" setter="set_flip_h" getter="is_flipped_h" default="false"> If [code]true[/code], texture is flipped horizontally. diff --git a/doc/classes/TileData.xml b/doc/classes/TileData.xml index 8aa5f1398a..91df90580c 100644 --- a/doc/classes/TileData.xml +++ b/doc/classes/TileData.xml @@ -70,22 +70,30 @@ <method name="get_navigation_polygon" qualifiers="const"> <return type="NavigationPolygon" /> <param index="0" name="layer_id" type="int" /> + <param index="1" name="flip_h" type="bool" default="false" /> + <param index="2" name="flip_v" type="bool" default="false" /> + <param index="3" name="transpose" type="bool" default="false" /> <description> Returns the navigation polygon of the tile for the TileSet navigation layer with index [param layer_id]. + [param flip_h], [param flip_v], and [param transpose] allow transforming the returned polygon. </description> </method> <method name="get_occluder" qualifiers="const"> <return type="OccluderPolygon2D" /> <param index="0" name="layer_id" type="int" /> + <param index="1" name="flip_h" type="bool" default="false" /> + <param index="2" name="flip_v" type="bool" default="false" /> + <param index="3" name="transpose" type="bool" default="false" /> <description> Returns the occluder polygon of the tile for the TileSet occlusion layer with index [param layer_id]. + [param flip_h], [param flip_v], and [param transpose] allow transforming the returned polygon. </description> </method> <method name="get_terrain_peering_bit" qualifiers="const"> <return type="int" /> <param index="0" name="peering_bit" type="int" enum="TileSet.CellNeighbor" /> <description> - Returns the tile's terrain bit for the given [param peering_bit] direction. + Returns the tile's terrain bit for the given [param peering_bit] direction. To check that a direction is valid, use [method is_valid_terrain_peering_bit]. </description> </method> <method name="is_collision_polygon_one_way" qualifiers="const"> @@ -96,6 +104,13 @@ Returns whether one-way collisions are enabled for the polygon at index [param polygon_index] for TileSet physics layer with index [param layer_id]. </description> </method> + <method name="is_valid_terrain_peering_bit" qualifiers="const"> + <return type="bool" /> + <param index="0" name="peering_bit" type="int" enum="TileSet.CellNeighbor" /> + <description> + Returns whether the given [param peering_bit] direction is valid for this tile. + </description> + </method> <method name="remove_collision_polygon"> <return type="void" /> <param index="0" name="layer_id" type="int" /> @@ -192,7 +207,7 @@ <param index="0" name="peering_bit" type="int" enum="TileSet.CellNeighbor" /> <param index="1" name="terrain" type="int" /> <description> - Sets the tile's terrain bit for the given [param peering_bit] direction. + Sets the tile's terrain bit for the given [param peering_bit] direction. To check that a direction is valid, use [method is_valid_terrain_peering_bit]. </description> </method> </methods> @@ -206,7 +221,7 @@ <member name="material" type="Material" setter="set_material" getter="get_material"> The [Material] to use for this [TileData]. This can be a [CanvasItemMaterial] to use the default shader, or a [ShaderMaterial] to use a custom shader. </member> - <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)"> + <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)" keywords="color, colour"> Color modulation of the tile. </member> <member name="probability" type="float" setter="set_probability" getter="get_probability" default="1.0"> diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index b08eb5c013..bc8a1d7bf1 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="TileMap" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="TileMap" inherits="Node2D" deprecated="Use multiple [TileMapLayer] nodes instead." keywords="gridmap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Node for 2D tile-based maps. </brief_description> <description> Node for 2D tile-based maps. Tilemaps use a [TileSet] which contain a list of tiles which are used to create grid-based maps. A TileMap may have several layers, layouting tiles on top of each other. - For performance reasons, all TileMap updates are batched at the end of a frame. Notably, this means that scene tiles from a [TileSetScenesCollectionSource] may be initialized after their parent. + For performance reasons, all TileMap updates are batched at the end of a frame. Notably, this means that scene tiles from a [TileSetScenesCollectionSource] may be initialized after their parent. This is only queued when inside the scene tree. To force an update earlier on, call [method update_internals]. </description> <tutorials> @@ -76,11 +76,11 @@ Clears cells that do not exist in the tileset. </description> </method> - <method name="force_update" is_deprecated="true"> + <method name="force_update" deprecated="Use [method notify_runtime_tile_data_update] and/or [method update_internals] instead."> <return type="void" /> <param index="0" name="layer" type="int" default="-1" /> <description> - [i]Deprecated.[/i] See [method notify_runtime_tile_data_update] and [method update_internals]. + Forces the TileMap and the layer [param layer] to update. </description> </method> <method name="get_cell_alternative_tile" qualifiers="const"> @@ -89,7 +89,8 @@ <param index="1" name="coords" type="Vector2i" /> <param index="2" name="use_proxies" type="bool" default="false" /> <description> - Returns the tile alternative ID of the cell on layer [param layer] at [param coords]. If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies, returning the raw alternative identifier. See [method TileSet.map_tile_proxy]. + Returns the tile alternative ID of the cell on layer [param layer] at [param coords]. + If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies, returning the raw alternative identifier. See [method TileSet.map_tile_proxy]. If [param layer] is negative, the layers are accessed from the last one. </description> </method> @@ -99,7 +100,8 @@ <param index="1" name="coords" type="Vector2i" /> <param index="2" name="use_proxies" type="bool" default="false" /> <description> - Returns the tile atlas coordinates ID of the cell on layer [param layer] at coordinates [param coords]. If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies, returning the raw alternative identifier. See [method TileSet.map_tile_proxy]. + Returns the tile atlas coordinates ID of the cell on layer [param layer] at coordinates [param coords]. Returns [code]Vector2i(-1, -1)[/code] if the cell does not exist. + If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies, returning the raw atlas coordinate identifier. See [method TileSet.map_tile_proxy]. If [param layer] is negative, the layers are accessed from the last one. </description> </method> @@ -110,7 +112,7 @@ <param index="2" name="use_proxies" type="bool" default="false" /> <description> Returns the tile source ID of the cell on layer [param layer] at coordinates [param coords]. Returns [code]-1[/code] if the cell does not exist. - If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies, returning the raw alternative identifier. See [method TileSet.map_tile_proxy]. + If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies, returning the raw source identifier. See [method TileSet.map_tile_proxy]. If [param layer] is negative, the layers are accessed from the last one. </description> </method> @@ -122,7 +124,6 @@ <description> Returns the [TileData] object associated with the given cell, or [code]null[/code] if the cell does not exist or is not a [TileSetAtlasSource]. If [param layer] is negative, the layers are accessed from the last one. - If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies, returning the raw alternative identifier. See [method TileSet.map_tile_proxy]. [codeblock] func get_clicked_tile_power(): var clicked_cell = tile_map.local_to_map(tile_map.get_local_mouse_position()) @@ -132,6 +133,7 @@ else: return 0 [/codeblock] + If [param use_proxies] is [code]false[/code], ignores the [TileSet]'s tile proxies. See [method TileSet.map_tile_proxy]. </description> </method> <method name="get_coords_for_body_rid"> @@ -168,7 +170,7 @@ <return type="RID" /> <param index="0" name="layer" type="int" /> <description> - Returns the [NavigationServer2D] navigation map [RID] currently assigned to the specified TileMap [param layer]. + Returns the [RID] of the [NavigationServer2D] navigation map assigned to the specified TileMap layer [param layer]. By default the TileMap uses the default [World2D] navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer. In order to make [NavigationAgent2D] switch between TileMap layer navigation maps use [method NavigationAgent2D.set_navigation_map] with the navigation map received from [method get_layer_navigation_map]. If [param layer] is negative, the layers are accessed from the last one. @@ -196,11 +198,11 @@ Returns the number of layers in the TileMap. </description> </method> - <method name="get_navigation_map" qualifiers="const" is_deprecated="true"> + <method name="get_navigation_map" qualifiers="const" deprecated="Use [method get_layer_navigation_map] instead."> <return type="RID" /> <param index="0" name="layer" type="int" /> <description> - See [method get_layer_navigation_map]. + Returns the [RID] of the [NavigationServer2D] navigation map assigned to the specified TileMap layer [param layer]. </description> </method> <method name="get_neighbor_cell" qualifiers="const"> @@ -375,7 +377,7 @@ <param index="0" name="layer" type="int" /> <param index="1" name="enabled" type="bool" /> <description> - Enables or disables the layer [param layer]. A disabled layer is not processed at all (no rendering, no physics, etc...). + Enables or disables the layer [param layer]. A disabled layer is not processed at all (no rendering, no physics, etc.). If [param layer] is negative, the layers are accessed from the last one. </description> </method> @@ -410,7 +412,7 @@ <param index="0" name="layer" type="int" /> <param index="1" name="map" type="RID" /> <description> - Assigns a [NavigationServer2D] navigation map [RID] to the specified TileMap [param layer]. + Assigns [param map] as a [NavigationServer2D] navigation map for the specified TileMap layer [param layer]. By default the TileMap uses the default [World2D] navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer. In order to make [NavigationAgent2D] switch between TileMap layer navigation maps use [method NavigationAgent2D.set_navigation_map] with the navigation map received from [method get_layer_navigation_map]. If [param layer] is negative, the layers are accessed from the last one. @@ -445,12 +447,12 @@ If [param layer] is negative, the layers are accessed from the last one. </description> </method> - <method name="set_navigation_map" is_deprecated="true"> + <method name="set_navigation_map" deprecated="Use [method set_layer_navigation_map] instead."> <return type="void" /> <param index="0" name="layer" type="int" /> <param index="1" name="map" type="RID" /> <description> - See [method set_layer_navigation_map]. + Assigns [param map] as a [NavigationServer2D] navigation map for the specified TileMap layer [param layer]. </description> </method> <method name="set_pattern"> @@ -489,7 +491,7 @@ [b]Note:[/b] As quadrants are created according to the map's coordinate system, the quadrant's "square shape" might not look like square in the TileMap's local coordinate system. </member> <member name="tile_set" type="TileSet" setter="set_tileset" getter="get_tileset"> - The assigned [TileSet]. + The [TileSet] used by this [TileMap]. The textures, collisions, and additional behavior of all available tiles are stored here. </member> </members> <signals> diff --git a/doc/classes/TileMapLayer.xml b/doc/classes/TileMapLayer.xml new file mode 100644 index 0000000000..bc8e259599 --- /dev/null +++ b/doc/classes/TileMapLayer.xml @@ -0,0 +1,303 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="TileMapLayer" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Node for 2D tile-based maps. + </brief_description> + <description> + Node for 2D tile-based maps. A [TileMapLayer] uses a [TileSet] which contain a list of tiles which are used to create grid-based maps. Unlike the [TileMap] node, which is deprecated, [TileMapLayer] has only one layer of tiles. You can use several [TileMapLayer] to achieve the same result as a [TileMap] node. + For performance reasons, all TileMap updates are batched at the end of a frame. Notably, this means that scene tiles from a [TileSetScenesCollectionSource] may be initialized after their parent. This is only queued when inside the scene tree. + To force an update earlier on, call [method update_internals]. + </description> + <tutorials> + </tutorials> + <methods> + <method name="_tile_data_runtime_update" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="coords" type="Vector2i" /> + <param index="1" name="tile_data" type="TileData" /> + <description> + Called with a [TileData] object about to be used internally by the [TileMapLayer], allowing its modification at runtime. + This method is only called if [method _use_tile_data_runtime_update] is implemented and returns [code]true[/code] for the given tile [param coords]. + [b]Warning:[/b] The [param tile_data] object's sub-resources are the same as the one in the TileSet. Modifying them might impact the whole TileSet. Instead, make sure to duplicate those resources. + [b]Note:[/b] If the properties of [param tile_data] object should change over time, use [method notify_runtime_tile_data_update] to notify the [TileMapLayer] it needs an update. + </description> + </method> + <method name="_use_tile_data_runtime_update" qualifiers="virtual"> + <return type="bool" /> + <param index="0" name="coords" type="Vector2i" /> + <description> + Should return [code]true[/code] if the tile at coordinates [param coords] requires a runtime update. + [b]Warning:[/b] Make sure this function only returns [code]true[/code] when needed. Any tile processed at runtime without a need for it will imply a significant performance penalty. + [b]Note:[/b] If the result of this function should change, use [method notify_runtime_tile_data_update] to notify the [TileMapLayer] it needs an update. + </description> + </method> + <method name="clear"> + <return type="void" /> + <description> + Clears all cells. + </description> + </method> + <method name="erase_cell"> + <return type="void" /> + <param index="0" name="coords" type="Vector2i" /> + <description> + Erases the cell at coordinates [param coords]. + </description> + </method> + <method name="fix_invalid_tiles"> + <return type="void" /> + <description> + Clears cells containing tiles that do not exist in the [member tile_set]. + </description> + </method> + <method name="get_cell_alternative_tile" qualifiers="const"> + <return type="int" /> + <param index="0" name="coords" type="Vector2i" /> + <description> + Returns the tile alternative ID of the cell at coordinates [param coords]. + </description> + </method> + <method name="get_cell_atlas_coords" qualifiers="const"> + <return type="Vector2i" /> + <param index="0" name="coords" type="Vector2i" /> + <description> + Returns the tile atlas coordinates ID of the cell at coordinates [param coords]. Returns [code]Vector2i(-1, -1)[/code] if the cell does not exist. + </description> + </method> + <method name="get_cell_source_id" qualifiers="const"> + <return type="int" /> + <param index="0" name="coords" type="Vector2i" /> + <description> + Returns the tile source ID of the cell at coordinates [param coords]. Returns [code]-1[/code] if the cell does not exist. + </description> + </method> + <method name="get_cell_tile_data" qualifiers="const"> + <return type="TileData" /> + <param index="0" name="coords" type="Vector2i" /> + <description> + Returns the [TileData] object associated with the given cell, or [code]null[/code] if the cell does not exist or is not a [TileSetAtlasSource]. + [codeblock] + func get_clicked_tile_power(): + var clicked_cell = tile_map_layer.local_to_map(tile_map_layer.get_local_mouse_position()) + var data = tile_map_layer.get_cell_tile_data(clicked_cell) + if data: + return data.get_custom_data("power") + else: + return 0 + [/codeblock] + </description> + </method> + <method name="get_coords_for_body_rid" qualifiers="const"> + <return type="Vector2i" /> + <param index="0" name="body" type="RID" /> + <description> + Returns the coordinates of the tile for given physics body [RID]. Such an [RID] can be retrieved from [method KinematicCollision2D.get_collider_rid], when colliding with a tile. + </description> + </method> + <method name="get_navigation_map" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of the [NavigationServer2D] navigation used by this [TileMapLayer]. + By default this returns the default [World2D] navigation map, unless a custom map was provided using [method set_navigation_map]. + </description> + </method> + <method name="get_neighbor_cell" qualifiers="const"> + <return type="Vector2i" /> + <param index="0" name="coords" type="Vector2i" /> + <param index="1" name="neighbor" type="int" enum="TileSet.CellNeighbor" /> + <description> + Returns the neighboring cell to the one at coordinates [param coords], identified by the [param neighbor] direction. This method takes into account the different layouts a TileMap can take. + </description> + </method> + <method name="get_pattern"> + <return type="TileMapPattern" /> + <param index="0" name="coords_array" type="Vector2i[]" /> + <description> + Creates and returns a new [TileMapPattern] from the given array of cells. See also [method set_pattern]. + </description> + </method> + <method name="get_surrounding_cells"> + <return type="Vector2i[]" /> + <param index="0" name="coords" type="Vector2i" /> + <description> + Returns the list of all neighboring cells to the one at [param coords]. + </description> + </method> + <method name="get_used_cells" qualifiers="const"> + <return type="Vector2i[]" /> + <description> + Returns a [Vector2i] array with the positions of all cells containing a tile. A cell is considered empty if its source identifier equals [code]-1[/code], its atlas coordinate identifier is [code]Vector2(-1, -1)[/code] and its alternative identifier is [code]-1[/code]. + </description> + </method> + <method name="get_used_cells_by_id" qualifiers="const"> + <return type="Vector2i[]" /> + <param index="0" name="source_id" type="int" default="-1" /> + <param index="1" name="atlas_coords" type="Vector2i" default="Vector2i(-1, -1)" /> + <param index="2" name="alternative_tile" type="int" default="-1" /> + <description> + Returns a [Vector2i] array with the positions of all cells containing a tile. Tiles may be filtered according to their source ([param source_id]), their atlas coordinates ([param atlas_coords]), or alternative id ([param alternative_tile]). + If a parameter has its value set to the default one, this parameter is not used to filter a cell. Thus, if all parameters have their respective default values, this method returns the same result as [method get_used_cells]. + A cell is considered empty if its source identifier equals [code]-1[/code], its atlas coordinate identifier is [code]Vector2(-1, -1)[/code] and its alternative identifier is [code]-1[/code]. + </description> + </method> + <method name="get_used_rect" qualifiers="const"> + <return type="Rect2i" /> + <description> + Returns a rectangle enclosing the used (non-empty) tiles of the map. + </description> + </method> + <method name="has_body_rid" qualifiers="const"> + <return type="bool" /> + <param index="0" name="body" type="RID" /> + <description> + Returns whether the provided [param body] [RID] belongs to one of this [TileMapLayer]'s cells. + </description> + </method> + <method name="local_to_map" qualifiers="const"> + <return type="Vector2i" /> + <param index="0" name="local_position" type="Vector2" /> + <description> + Returns the map coordinates of the cell containing the given [param local_position]. If [param local_position] is in global coordinates, consider using [method Node2D.to_local] before passing it to this method. See also [method map_to_local]. + </description> + </method> + <method name="map_pattern"> + <return type="Vector2i" /> + <param index="0" name="position_in_tilemap" type="Vector2i" /> + <param index="1" name="coords_in_pattern" type="Vector2i" /> + <param index="2" name="pattern" type="TileMapPattern" /> + <description> + Returns for the given coordinates [param coords_in_pattern] in a [TileMapPattern] the corresponding cell coordinates if the pattern was pasted at the [param position_in_tilemap] coordinates (see [method set_pattern]). This mapping is required as in half-offset tile shapes, the mapping might not work by calculating [code]position_in_tile_map + coords_in_pattern[/code]. + </description> + </method> + <method name="map_to_local" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="map_position" type="Vector2i" /> + <description> + Returns the centered position of a cell in the [TileMapLayer]'s local coordinate space. To convert the returned value into global coordinates, use [method Node2D.to_global]. See also [method local_to_map]. + [b]Note:[/b] This may not correspond to the visual position of the tile, i.e. it ignores the [member TileData.texture_origin] property of individual tiles. + </description> + </method> + <method name="notify_runtime_tile_data_update"> + <return type="void" /> + <description> + Notifies the [TileMapLayer] node that calls to [method _use_tile_data_runtime_update] or [method _tile_data_runtime_update] will lead to different results. This will thus trigger a [TileMapLayer] update. + [b]Warning:[/b] Updating the [TileMapLayer] is computationally expensive and may impact performance. Try to limit the number of calls to this function to avoid unnecessary update. + [b]Note:[/b] This does not trigger a direct update of the [TileMapLayer], the update will be done at the end of the frame as usual (unless you call [method update_internals]). + </description> + </method> + <method name="set_cell"> + <return type="void" /> + <param index="0" name="coords" type="Vector2i" /> + <param index="1" name="source_id" type="int" default="-1" /> + <param index="2" name="atlas_coords" type="Vector2i" default="Vector2i(-1, -1)" /> + <param index="3" name="alternative_tile" type="int" default="0" /> + <description> + Sets the tile identifiers for the cell at coordinates [param coords]. Each tile of the [TileSet] is identified using three parts: + - The source identifier [param source_id] identifies a [TileSetSource] identifier. See [method TileSet.set_source_id], + - The atlas coordinate identifier [param atlas_coords] identifies a tile coordinates in the atlas (if the source is a [TileSetAtlasSource]). For [TileSetScenesCollectionSource] it should always be [code]Vector2i(0, 0)[/code], + - The alternative tile identifier [param alternative_tile] identifies a tile alternative in the atlas (if the source is a [TileSetAtlasSource]), and the scene for a [TileSetScenesCollectionSource]. + If [param source_id] is set to [code]-1[/code], [param atlas_coords] to [code]Vector2i(-1, -1)[/code], or [param alternative_tile] to [code]-1[/code], the cell will be erased. An erased cell gets [b]all[/b] its identifiers automatically set to their respective invalid values, namely [code]-1[/code], [code]Vector2i(-1, -1)[/code] and [code]-1[/code]. + </description> + </method> + <method name="set_cells_terrain_connect"> + <return type="void" /> + <param index="0" name="cells" type="Vector2i[]" /> + <param index="1" name="terrain_set" type="int" /> + <param index="2" name="terrain" type="int" /> + <param index="3" name="ignore_empty_terrains" type="bool" default="true" /> + <description> + Update all the cells in the [param cells] coordinates array so that they use the given [param terrain] for the given [param terrain_set]. If an updated cell has the same terrain as one of its neighboring cells, this function tries to join the two. This function might update neighboring tiles if needed to create correct terrain transitions. + If [param ignore_empty_terrains] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + [b]Note:[/b] To work correctly, this method requires the [TileMapLayer]'s TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. + </description> + </method> + <method name="set_cells_terrain_path"> + <return type="void" /> + <param index="0" name="path" type="Vector2i[]" /> + <param index="1" name="terrain_set" type="int" /> + <param index="2" name="terrain" type="int" /> + <param index="3" name="ignore_empty_terrains" type="bool" default="true" /> + <description> + Update all the cells in the [param path] coordinates array so that they use the given [param terrain] for the given [param terrain_set]. The function will also connect two successive cell in the path with the same terrain. This function might update neighboring tiles if needed to create correct terrain transitions. + If [param ignore_empty_terrains] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + [b]Note:[/b] To work correctly, this method requires the [TileMapLayer]'s TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. + </description> + </method> + <method name="set_navigation_map"> + <return type="void" /> + <param index="0" name="map" type="RID" /> + <description> + Sets a custom [param map] as a [NavigationServer2D] navigation map. If not set, uses the default [World2D] navigation map instead. + </description> + </method> + <method name="set_pattern"> + <return type="void" /> + <param index="0" name="position" type="Vector2i" /> + <param index="1" name="pattern" type="TileMapPattern" /> + <description> + Pastes the [TileMapPattern] at the given [param position] in the tile map. See also [method get_pattern]. + </description> + </method> + <method name="update_internals"> + <return type="void" /> + <description> + Triggers a direct update of the [TileMapLayer]. Usually, calling this function is not needed, as [TileMapLayer] node updates automatically when one of its properties or cells is modified. + However, for performance reasons, those updates are batched and delayed to the end of the frame. Calling this function will force the [TileMapLayer] to update right away instead. + [b]Warning:[/b] Updating the [TileMapLayer] is computationally expensive and may impact performance. Try to limit the number of updates and how many tiles they impact. + </description> + </method> + </methods> + <members> + <member name="collision_enabled" type="bool" setter="set_collision_enabled" getter="is_collision_enabled" default="true"> + Enable or disable collisions. + </member> + <member name="collision_visibility_mode" type="int" setter="set_collision_visibility_mode" getter="get_collision_visibility_mode" enum="TileMapLayer.DebugVisibilityMode" default="0"> + Show or hide the [TileMapLayer]'s collision shapes. If set to [constant DEBUG_VISIBILITY_MODE_DEFAULT], this depends on the show collision debug settings. + </member> + <member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true"> + If [code]false[/code], disables this [TileMapLayer] completely (rendering, collision, navigation, scene tiles, etc.) + </member> + <member name="navigation_enabled" type="bool" setter="set_navigation_enabled" getter="is_navigation_enabled" default="true"> + If [code]true[/code], navigation regions are enabled. + </member> + <member name="navigation_visibility_mode" type="int" setter="set_navigation_visibility_mode" getter="get_navigation_visibility_mode" enum="TileMapLayer.DebugVisibilityMode" default="0"> + Show or hide the [TileMapLayer]'s navigation meshes. If set to [constant DEBUG_VISIBILITY_MODE_DEFAULT], this depends on the show navigation debug settings. + </member> + <member name="rendering_quadrant_size" type="int" setter="set_rendering_quadrant_size" getter="get_rendering_quadrant_size" default="16"> + The [TileMapLayer]'s quadrant size. A quadrant is a group of tiles to be drawn together on a single canvas item, for optimization purposes. [member rendering_quadrant_size] defines the length of a square's side, in the map's coordinate system, that forms the quadrant. Thus, the default quandrant size groups together [code]16 * 16 = 256[/code] tiles. + The quadrant size does not apply on a Y-sorted [TileMapLayer], as tiles are be grouped by Y position instead in that case. + [b]Note:[/b] As quadrants are created according to the map's coordinate system, the quadrant's "square shape" might not look like square in the [TileMapLayer]'s local coordinate system. + </member> + <member name="tile_map_data" type="PackedByteArray" setter="set_tile_map_data_from_array" getter="get_tile_map_data_as_array" default="PackedByteArray(0, 0)"> + The raw tile map data as a byte array. + </member> + <member name="tile_set" type="TileSet" setter="set_tile_set" getter="get_tile_set"> + The [TileSet] used by this layer. The textures, collisions, and additional behavior of all available tiles are stored here. + </member> + <member name="use_kinematic_bodies" type="bool" setter="set_use_kinematic_bodies" getter="is_using_kinematic_bodies" default="false"> + If [code]true[/code], this [TileMapLayer] collision shapes will be instantiated as kinematic bodies. This can be needed for moving [TileMapLayer] nodes (i.e. moving platforms). + </member> + <member name="y_sort_origin" type="int" setter="set_y_sort_origin" getter="get_y_sort_origin" default="0"> + This Y-sort origin value is added to each tile's Y-sort origin value. This allows, for example, to fake a different height level. This can be useful for top-down view games. + </member> + </members> + <signals> + <signal name="changed"> + <description> + Emitted when this [TileMapLayer]'s properties changes. This includes modified cells, properties, or changes made to its assigned [TileSet]. + [b]Note:[/b] This signal may be emitted very often when batch-modifying a [TileMapLayer]. Avoid executing complex processing in a connected function, and consider delaying it to the end of the frame instead (i.e. calling [method Object.call_deferred]). + </description> + </signal> + </signals> + <constants> + <constant name="DEBUG_VISIBILITY_MODE_DEFAULT" value="0" enum="DebugVisibilityMode"> + Hide the collisions or navigation debug shapes in the editor, and use the debug settings to determine their visibility in game (i.e. [member SceneTree.debug_collisions_hint] or [member SceneTree.debug_navigation_hint]). + </constant> + <constant name="DEBUG_VISIBILITY_MODE_FORCE_HIDE" value="2" enum="DebugVisibilityMode"> + Always hide the collisions or navigation debug shapes. + </constant> + <constant name="DEBUG_VISIBILITY_MODE_FORCE_SHOW" value="1" enum="DebugVisibilityMode"> + Always show the collisions or navigation debug shapes. + </constant> + </constants> +</class> diff --git a/doc/classes/TileSetAtlasSource.xml b/doc/classes/TileSetAtlasSource.xml index 755c266cd9..6f212274f8 100644 --- a/doc/classes/TileSetAtlasSource.xml +++ b/doc/classes/TileSetAtlasSource.xml @@ -90,7 +90,7 @@ <return type="int" enum="TileSetAtlasSource.TileAnimationMode" /> <param index="0" name="atlas_coords" type="Vector2i" /> <description> - Returns the [enum TileAnimationMode] of the tile at [param atlas_coords]. See also [method set_tile_animation_mode]. + Returns the tile animation mode of the tile at [param atlas_coords]. See also [method set_tile_animation_mode]. </description> </method> <method name="get_tile_animation_separation" qualifiers="const"> @@ -239,7 +239,7 @@ <param index="0" name="atlas_coords" type="Vector2i" /> <param index="1" name="mode" type="int" enum="TileSetAtlasSource.TileAnimationMode" /> <description> - Sets the [enum TileAnimationMode] of the tile at [param atlas_coords] to [param mode]. See also [method get_tile_animation_mode]. + Sets the tile animation mode of the tile at [param atlas_coords] to [param mode]. See also [method get_tile_animation_mode]. </description> </method> <method name="set_tile_animation_separation"> diff --git a/doc/classes/Time.xml b/doc/classes/Time.xml index 79c332327f..2948d20fbb 100644 --- a/doc/classes/Time.xml +++ b/doc/classes/Time.xml @@ -7,7 +7,7 @@ The Time singleton allows converting time between various formats and also getting time information from the system. This class conforms with as many of the ISO 8601 standards as possible. All dates follow the Proleptic Gregorian calendar. As such, the day before [code]1582-10-15[/code] is [code]1582-10-14[/code], not [code]1582-10-04[/code]. The year before 1 AD (aka 1 BC) is number [code]0[/code], with the year before that (2 BC) being [code]-1[/code], etc. Conversion methods assume "the same timezone", and do not handle timezone conversions or DST automatically. Leap seconds are also not handled, they must be done manually if desired. Suffixes such as "Z" are not handled, you need to strip them away manually. - When getting time information from the system, the time can either be in the local timezone or UTC depending on the [code]utc[/code] parameter. However, the [method get_unix_time_from_system] method always returns the time in UTC. + When getting time information from the system, the time can either be in the local timezone or UTC depending on the [code]utc[/code] parameter. However, the [method get_unix_time_from_system] method always uses UTC as it returns the seconds passed since the [url=https://en.wikipedia.org/wiki/Unix_time]Unix epoch[/url]. [b]Important:[/b] The [code]_from_system[/code] methods use the system clock that the user can manually set. [b]Never use[/b] this method for precise time calculation since its results are subject to automatic adjustments by the user or the operating system. [b]Always use[/b] [method get_ticks_usec] or [method get_ticks_msec] for precise time calculation instead, since they are guaranteed to be monotonic (i.e. never decrease). </description> <tutorials> @@ -180,7 +180,7 @@ <method name="get_unix_time_from_system" qualifiers="const"> <return type="float" /> <description> - Returns the current Unix timestamp in seconds based on the system time in UTC. This method is implemented by the operating system and always returns the time in UTC. + Returns the current Unix timestamp in seconds based on the system time in UTC. This method is implemented by the operating system and always returns the time in UTC. The Unix timestamp is the number of seconds passed since 1970-01-01 at 00:00:00, the [url=https://en.wikipedia.org/wiki/Unix_time]Unix epoch[/url]. [b]Note:[/b] Unlike other methods that use integer timestamps, this method returns the timestamp as a [float] for sub-second precision. </description> </method> diff --git a/doc/classes/Timer.xml b/doc/classes/Timer.xml index 03a651ad9a..6eee569443 100644 --- a/doc/classes/Timer.xml +++ b/doc/classes/Timer.xml @@ -4,9 +4,15 @@ A countdown timer. </brief_description> <description> - Counts down a specified interval and emits a signal on reaching 0. Can be set to repeat or "one-shot" mode. - [b]Note:[/b] Timers are affected by [member Engine.time_scale], a higher scale means quicker timeouts, and vice versa. + The [Timer] node is a countdown timer and is the simplest way to handle time-based logic in the engine. When a timer reaches the end of its [member wait_time], it will emit the [signal timeout] signal. + After a timer enters the tree, it can be manually started with [method start]. A timer node is also started automatically if [member autostart] is [code]true[/code]. + Without requiring much code, a timer node can be added and configured in the editor. The [signal timeout] signal it emits can also be connected through the Node dock in the editor: + [codeblock] + func _on_timer_timeout(): + print("Time to attack!") + [/codeblock] [b]Note:[/b] To create a one-shot timer without instantiating a node, use [method SceneTree.create_timer]. + [b]Note:[/b] Timers are affected by [member Engine.time_scale]. The higher the time scale, the sooner timers will end. How often a timer processes may depend on the framerate or [member Engine.physics_ticks_per_second]. </description> <tutorials> <link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/515</link> @@ -15,15 +21,15 @@ <method name="is_stopped" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the timer is stopped. + Returns [code]true[/code] if the timer is stopped or has not started. </description> </method> <method name="start"> <return type="void" /> <param index="0" name="time_sec" type="float" default="-1" /> <description> - Starts the timer. Sets [member wait_time] to [param time_sec] if [code]time_sec > 0[/code]. This also resets the remaining time to [member wait_time]. - [b]Note:[/b] This method will not resume a paused timer. See [member paused]. + Starts the timer, if it was not started already. Fails if the timer is not inside the tree. If [param time_sec] is greater than [code]0[/code], this value is used for the [member wait_time]. + [b]Note:[/b] This method does not resume a paused timer. See [member paused]. </description> </method> <method name="stop"> @@ -35,40 +41,40 @@ </methods> <members> <member name="autostart" type="bool" setter="set_autostart" getter="has_autostart" default="false"> - If [code]true[/code], the timer will automatically start when entering the scene tree. - [b]Note:[/b] This property is automatically set to [code]false[/code] after the timer enters the scene tree and starts. + If [code]true[/code], the timer will start immediately when it enters the scene tree. + [b]Note:[/b] After the timer enters the tree, this property is automatically set to [code]false[/code]. </member> <member name="one_shot" type="bool" setter="set_one_shot" getter="is_one_shot" default="false"> - If [code]true[/code], the timer will stop when reaching 0. If [code]false[/code], it will restart. + If [code]true[/code], the timer will stop after reaching the end. Otherwise, as by default, the timer will automatically restart. </member> <member name="paused" type="bool" setter="set_paused" getter="is_paused"> - If [code]true[/code], the timer is paused and will not process until it is unpaused again, even if [method start] is called. + If [code]true[/code], the timer is paused. A paused timer does not process until this property is set back to [code]false[/code], even when [method start] is called. </member> <member name="process_callback" type="int" setter="set_timer_process_callback" getter="get_timer_process_callback" enum="Timer.TimerProcessCallback" default="1"> - Processing callback. See [enum TimerProcessCallback]. + Specifies when the timer is updated during the main loop (see [enum TimerProcessCallback]). </member> <member name="time_left" type="float" setter="" getter="get_time_left"> - The timer's remaining time in seconds. Returns 0 if the timer is inactive. - [b]Note:[/b] This value is read-only and cannot be set. It is based on [member wait_time], which can be set using [method start]. + The timer's remaining time in seconds. This is always [code]0[/code] if the timer is stopped. + [b]Note:[/b] This property is read-only and cannot be modified. It is based on [member wait_time]. </member> <member name="wait_time" type="float" setter="set_wait_time" getter="get_wait_time" default="1.0"> - The wait time in seconds. - [b]Note:[/b] Timers can only emit once per rendered frame at most (or once per physics frame if [member process_callback] is [constant TIMER_PROCESS_PHYSICS]). This means very low wait times (lower than 0.05 seconds) will behave in significantly different ways depending on the rendered framerate. For very low wait times, it is recommended to use a process loop in a script instead of using a Timer node. Timers are affected by [member Engine.time_scale], a higher scale means quicker timeouts, and vice versa. + The time required for the timer to end, in seconds. This property can also be set every time [method start] is called. + [b]Note:[/b] Timers can only process once per physics or process frame (depending on the [member process_callback]). An unstable framerate may cause the timer to end inconsistently, which is especially noticeable if the wait time is lower than roughly [code]0.05[/code] seconds. For very short timers, it is recommended to write your own code instead of using a [Timer] node. Timers are also affected by [member Engine.time_scale]. </member> </members> <signals> <signal name="timeout"> <description> - Emitted when the timer reaches 0. + Emitted when the timer reaches the end. </description> </signal> </signals> <constants> <constant name="TIMER_PROCESS_PHYSICS" value="0" enum="TimerProcessCallback"> - Update the timer during physics frames (see [constant Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS]). + Update the timer every physics process frame (see [constant Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS]). </constant> <constant name="TIMER_PROCESS_IDLE" value="1" enum="TimerProcessCallback"> - Update the timer during process frames (see [constant Node.NOTIFICATION_INTERNAL_PROCESS]). + Update the timer every process (rendered) frame (see [constant Node.NOTIFICATION_INTERNAL_PROCESS]). </constant> </constants> </class> diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml index aee70f6b59..4247ff81ee 100644 --- a/doc/classes/Transform2D.xml +++ b/doc/classes/Transform2D.xml @@ -5,7 +5,7 @@ </brief_description> <description> A 2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of three [Vector2] values: [member x], [member y], and the [member origin]. - For more information, read the "Matrices and transforms" documentation article. + For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial. </description> <tutorials> <link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link> @@ -286,6 +286,20 @@ This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly. </description> </operator> + <operator name="operator /"> + <return type="Transform2D" /> + <param index="0" name="right" type="float" /> + <description> + This operator divides all components of the [Transform2D], including the [member origin] vector, which inversely scales it uniformly. + </description> + </operator> + <operator name="operator /"> + <return type="Transform2D" /> + <param index="0" name="right" type="int" /> + <description> + This operator divides all components of the [Transform2D], including the [member origin] vector, which inversely scales it uniformly. + </description> + </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="Transform2D" /> diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index 85da629d70..1827cdf8f0 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -4,8 +4,9 @@ A 3×4 matrix representing a 3D transformation. </brief_description> <description> - A 3×4 matrix (3 rows, 4 columns) used for 3D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of a [member basis] (first 3 columns) and a [Vector3] for the [member origin] (last column). - For more information, read the "Matrices and transforms" documentation article. + The [Transform3D] built-in [Variant] type is a 3×4 matrix representing a transformation in 3D space. It contains a [Basis], which on its own can represent rotation, scale, and shear. Additionally, combined with its own [member origin], the transform can also represent a translation. + For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial. + [b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions]Importing 3D Scenes[/url] tutorial. </description> <tutorials> <link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link> @@ -19,7 +20,7 @@ <constructor name="Transform3D"> <return type="Transform3D" /> <description> - Constructs a default-initialized [Transform3D] set to [constant IDENTITY]. + Constructs a [Transform3D] identical to the [constant IDENTITY]. </description> </constructor> <constructor name="Transform3D"> @@ -34,14 +35,14 @@ <param index="0" name="basis" type="Basis" /> <param index="1" name="origin" type="Vector3" /> <description> - Constructs a Transform3D from a [Basis] and [Vector3]. + Constructs a [Transform3D] from a [Basis] and [Vector3]. </description> </constructor> <constructor name="Transform3D"> <return type="Transform3D" /> <param index="0" name="from" type="Projection" /> <description> - Constructs a Transform3D from a [Projection] by trimming the last row of the projection matrix ([code]from.x.w[/code], [code]from.y.w[/code], [code]from.z.w[/code], and [code]from.w.w[/code] are not copied over). + Constructs a [Transform3D] from a [Projection]. Because [Transform3D] is a 3×4 matrix and [Projection] is a 4×4 matrix, this operation trims the last row of the projection matrix ([code]from.x.w[/code], [code]from.y.w[/code], [code]from.z.w[/code], and [code]from.w.w[/code] are not included in the new transform). </description> </constructor> <constructor name="Transform3D"> @@ -51,7 +52,8 @@ <param index="2" name="z_axis" type="Vector3" /> <param index="3" name="origin" type="Vector3" /> <description> - Constructs a Transform3D from four [Vector3] values (matrix columns). Each axis corresponds to local basis vectors (some of which may be scaled). + Constructs a [Transform3D] from four [Vector3] values (also called matrix columns). + The first three arguments are the [member basis]'s axes ([member Basis.x], [member Basis.y], and [member Basis.z]). </description> </constructor> </constructors> @@ -59,7 +61,8 @@ <method name="affine_inverse" qualifiers="const"> <return type="Transform3D" /> <description> - Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant). + Returns the inverted version of this transform. Unlike [method inverse], this method works with almost any [member basis], including non-uniform ones, but is slower. See also [method Basis.inverse]. + [b]Note:[/b] For this method to return correctly, the transform's [member basis] needs to have a determinant that is not exactly [code]0[/code] (see [method Basis.determinant]). </description> </method> <method name="interpolate_with" qualifiers="const"> @@ -67,13 +70,15 @@ <param index="0" name="xform" type="Transform3D" /> <param index="1" name="weight" type="float" /> <description> - Returns a transform interpolated between this transform and another by a given [param weight] (on the range of 0.0 to 1.0). + Returns the result of the linear interpolation between this transform and [param xform] by the given [param weight]. + The [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). Values outside this range are allowed and can be used to perform [i]extrapolation[/i] instead. </description> </method> <method name="inverse" qualifiers="const"> <return type="Transform3D" /> <description> - Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use [method affine_inverse] for non-orthonormal transforms (e.g. with scaling). + Returns the inverted version of this transform. See also [method Basis.inverse]. + [b]Note:[/b] For this method to return correctly, the transform's [member basis] needs to be [i]orthonormal[/i] (see [method Basis.orthonormalized]). That means, the basis should only represent a rotation. If it does not, use [method affine_inverse] instead. </description> </method> <method name="is_equal_approx" qualifiers="const"> @@ -95,7 +100,7 @@ <param index="1" name="up" type="Vector3" default="Vector3(0, 1, 0)" /> <param index="2" name="use_model_front" type="bool" default="false" /> <description> - Returns a copy of the transform rotated such that the forward axis (-Z) points towards the [param target] position. + Returns a copy of this transform rotated so that the forward axis (-Z) points towards the [param target] position. The up axis (+Y) points as close to the [param up] vector as possible while staying perpendicular to the forward axis. The resulting transform is orthonormalized. The existing rotation, scale, and skew information from the original transform is discarded. The [param target] and [param up] vectors cannot be zero, cannot be parallel to each other, and are defined in global/parent space. If [param use_model_front] is [code]true[/code], the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the [param target] position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right). </description> @@ -103,7 +108,7 @@ <method name="orthonormalized" qualifiers="const"> <return type="Transform3D" /> <description> - Returns the transform with the basis orthogonal (90 degrees), and normalized axis vectors (scale of 1 or -1). + Returns a copy of this transform with its [member basis] orthonormalized. An orthonormal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]normalized[/i] (the axes have a length of [code]1[/code]), which also means it can only represent rotation. See also [method Basis.orthonormalized]. </description> </method> <method name="rotated" qualifiers="const"> @@ -111,7 +116,7 @@ <param index="0" name="axis" type="Vector3" /> <param index="1" name="angle" type="float" /> <description> - Returns a copy of the transform rotated around the given [param axis] by the given [param angle] (in radians). + Returns a copy of this transform rotated around the given [param axis] by the given [param angle] (in radians). The [param axis] must be a normalized vector. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding rotation transform [code]R[/code] from the left, i.e., [code]R * X[/code]. This can be seen as transforming with respect to the global/parent frame. @@ -122,7 +127,7 @@ <param index="0" name="axis" type="Vector3" /> <param index="1" name="angle" type="float" /> <description> - Returns a copy of the transform rotated around the given [param axis] by the given [param angle] (in radians). + Returns a copy of this transform rotated around the given [param axis] by the given [param angle] (in radians). The [param axis] must be a normalized vector. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding rotation transform [code]R[/code] from the right, i.e., [code]X * R[/code]. This can be seen as transforming with respect to the local frame. @@ -132,7 +137,7 @@ <return type="Transform3D" /> <param index="0" name="scale" type="Vector3" /> <description> - Returns a copy of the transform scaled by the given [param scale] factor. + Returns a copy of this transform scaled by the given [param scale] factor. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding scaling transform [code]S[/code] from the left, i.e., [code]S * X[/code]. This can be seen as transforming with respect to the global/parent frame. </description> @@ -141,7 +146,7 @@ <return type="Transform3D" /> <param index="0" name="scale" type="Vector3" /> <description> - Returns a copy of the transform scaled by the given [param scale] factor. + Returns a copy of this transform scaled by the given [param scale] factor. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding scaling transform [code]S[/code] from the right, i.e., [code]X * S[/code]. This can be seen as transforming with respect to the local frame. </description> @@ -150,7 +155,7 @@ <return type="Transform3D" /> <param index="0" name="offset" type="Vector3" /> <description> - Returns a copy of the transform translated by the given [param offset]. + Returns a copy of this transform translated by the given [param offset]. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding translation transform [code]T[/code] from the left, i.e., [code]T * X[/code]. This can be seen as transforming with respect to the global/parent frame. </description> @@ -159,7 +164,7 @@ <return type="Transform3D" /> <param index="0" name="offset" type="Vector3" /> <description> - Returns a copy of the transform translated by the given [param offset]. + Returns a copy of this transform translated by the given [param offset]. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding translation transform [code]T[/code] from the right, i.e., [code]X * T[/code]. This can be seen as transforming with respect to the local frame. </description> @@ -167,24 +172,25 @@ </methods> <members> <member name="basis" type="Basis" setter="" getter="" default="Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)"> - The basis is a matrix containing 3 [Vector3] as its columns: X axis, Y axis, and Z axis. These vectors can be interpreted as the basis vectors of local coordinate system traveling with the object. + The [Basis] of this transform. It is composed by 3 axes ([member Basis.x], [member Basis.y], and [member Basis.z]). Together, these represent the transform's rotation, scale, and shear. </member> <member name="origin" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)"> - The translation offset of the transform (column 3, the fourth column). Equivalent to array index [code]3[/code]. + The translation offset of this transform. In 3D space, this can be seen as the position. </member> </members> <constants> <constant name="IDENTITY" value="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)"> - [Transform3D] with no translation, rotation or scaling applied. When applied to other data structures, [constant IDENTITY] performs no transformation. + A transform with no translation, no rotation, and its scale being [code]1[/code]. Its [member basis] is equal to [constant Basis.IDENTITY]. + When multiplied by another [Variant] such as [AABB] or another [Transform3D], no transformation occurs. </constant> <constant name="FLIP_X" value="Transform3D(-1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)"> - [Transform3D] with mirroring applied perpendicular to the YZ plane. + [Transform3D] with mirroring applied perpendicular to the YZ plane. Its [member basis] is equal to [constant Basis.FLIP_X]. </constant> <constant name="FLIP_Y" value="Transform3D(1, 0, 0, 0, -1, 0, 0, 0, 1, 0, 0, 0)"> - [Transform3D] with mirroring applied perpendicular to the XZ plane. + [Transform3D] with mirroring applied perpendicular to the XZ plane. Its [member basis] is equal to [constant Basis.FLIP_Y]. </constant> <constant name="FLIP_Z" value="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, -1, 0, 0, 0)"> - [Transform3D] with mirroring applied perpendicular to the XY plane. + [Transform3D] with mirroring applied perpendicular to the XY plane. Its [member basis] is equal to [constant Basis.FLIP_Z]. </constant> </constants> <operators> @@ -192,7 +198,7 @@ <return type="bool" /> <param index="0" name="right" type="Transform3D" /> <description> - Returns [code]true[/code] if the transforms are not equal. + Returns [code]true[/code] if the components of both transforms are not equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -200,56 +206,76 @@ <return type="AABB" /> <param index="0" name="right" type="AABB" /> <description> - Transforms (multiplies) the [AABB] by the given [Transform3D] matrix. + Transforms (multiplies) the [AABB] by this transformation matrix. </description> </operator> <operator name="operator *"> <return type="PackedVector3Array" /> <param index="0" name="right" type="PackedVector3Array" /> <description> - Transforms (multiplies) each element of the [Vector3] array by the given [Transform3D] matrix. + Transforms (multiplies) every [Vector3] element of the given [PackedVector3Array] by this transformation matrix. + On larger arrays, this operation is much faster than transforming each [Vector3] individually. </description> </operator> <operator name="operator *"> <return type="Plane" /> <param index="0" name="right" type="Plane" /> <description> - Transforms (multiplies) the [Plane] by the given [Transform3D] transformation matrix. + Transforms (multiplies) the [Plane] by this transformation matrix. </description> </operator> <operator name="operator *"> <return type="Transform3D" /> <param index="0" name="right" type="Transform3D" /> <description> - Composes these two transformation matrices by multiplying them together. This has the effect of transforming the second transform (the child) by the first transform (the parent). + Transforms (multiplies) this transform by the [param right] transform. + This is the operation performed between parent and child [Node3D]s. + [b]Note:[/b] If you need to only modify one attribute of this transform, consider using one of the following methods, instead: + - For translation, see [method translated] or [method translated_local]. + - For rotation, see [method rotated] or [method rotated_local]. + - For scale, see [method scaled] or [method scaled_local]. </description> </operator> <operator name="operator *"> <return type="Vector3" /> <param index="0" name="right" type="Vector3" /> <description> - Transforms (multiplies) the [Vector3] by the given [Transform3D] matrix. + Transforms (multiplies) the [Vector3] by this transformation matrix. </description> </operator> <operator name="operator *"> <return type="Transform3D" /> <param index="0" name="right" type="float" /> <description> - This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly. + Multiplies all components of the [Transform3D] by the given [float], including the [member origin]. This affects the transform's scale uniformly, scaling the [member basis]. </description> </operator> <operator name="operator *"> <return type="Transform3D" /> <param index="0" name="right" type="int" /> <description> - This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly. + Multiplies all components of the [Transform3D] by the given [int], including the [member origin]. This affects the transform's scale uniformly, scaling the [member basis]. + </description> + </operator> + <operator name="operator /"> + <return type="Transform3D" /> + <param index="0" name="right" type="float" /> + <description> + Divides all components of the [Transform3D] by the given [float], including the [member origin]. This affects the transform's scale uniformly, scaling the [member basis]. + </description> + </operator> + <operator name="operator /"> + <return type="Transform3D" /> + <param index="0" name="right" type="int" /> + <description> + Divides all components of the [Transform3D] by the given [int], including the [member origin]. This affects the transform's scale uniformly, scaling the [member basis]. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="Transform3D" /> <description> - Returns [code]true[/code] if the transforms are exactly equal. + Returns [code]true[/code] if the components of both transforms are exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> diff --git a/doc/classes/Translation.xml b/doc/classes/Translation.xml index 194b3be854..cc63247266 100644 --- a/doc/classes/Translation.xml +++ b/doc/classes/Translation.xml @@ -33,7 +33,7 @@ <return type="void" /> <param index="0" name="src_message" type="StringName" /> <param index="1" name="xlated_message" type="StringName" /> - <param index="2" name="context" type="StringName" default="""" /> + <param index="2" name="context" type="StringName" default="&""" /> <description> Adds a message if nonexistent, followed by its translation. An additional context could be used to specify the translation context or differentiate polysemic words. @@ -43,7 +43,7 @@ <return type="void" /> <param index="0" name="src_message" type="StringName" /> <param index="1" name="xlated_messages" type="PackedStringArray" /> - <param index="2" name="context" type="StringName" default="""" /> + <param index="2" name="context" type="StringName" default="&""" /> <description> Adds a message involving plural translation if nonexistent, followed by its translation. An additional context could be used to specify the translation context or differentiate polysemic words. @@ -52,7 +52,7 @@ <method name="erase_message"> <return type="void" /> <param index="0" name="src_message" type="StringName" /> - <param index="1" name="context" type="StringName" default="""" /> + <param index="1" name="context" type="StringName" default="&""" /> <description> Erases a message. </description> @@ -60,7 +60,7 @@ <method name="get_message" qualifiers="const"> <return type="StringName" /> <param index="0" name="src_message" type="StringName" /> - <param index="1" name="context" type="StringName" default="""" /> + <param index="1" name="context" type="StringName" default="&""" /> <description> Returns a message's translation. </description> @@ -82,7 +82,7 @@ <param index="0" name="src_message" type="StringName" /> <param index="1" name="src_plural_message" type="StringName" /> <param index="2" name="n" type="int" /> - <param index="3" name="context" type="StringName" default="""" /> + <param index="3" name="context" type="StringName" default="&""" /> <description> Returns a message's translation involving plurals. The number [param n] is the number or quantity of the plural object. It will be used to guide the translation system to fetch the correct plural form for the selected language. diff --git a/doc/classes/TranslationServer.xml b/doc/classes/TranslationServer.xml index 3a4cd06013..db1a65278c 100644 --- a/doc/classes/TranslationServer.xml +++ b/doc/classes/TranslationServer.xml @@ -144,7 +144,7 @@ <method name="translate" qualifiers="const"> <return type="StringName" /> <param index="0" name="message" type="StringName" /> - <param index="1" name="context" type="StringName" default="""" /> + <param index="1" name="context" type="StringName" default="&""" /> <description> Returns the current locale's translation for the given message (key) and context. </description> @@ -154,7 +154,7 @@ <param index="0" name="message" type="StringName" /> <param index="1" name="plural_message" type="StringName" /> <param index="2" name="n" type="int" /> - <param index="3" name="context" type="StringName" default="""" /> + <param index="3" name="context" type="StringName" default="&""" /> <description> Returns the current locale's translation for the given message (key), plural message and context. The number [param n] is the number or quantity of the plural object. It will be used to guide the translation system to fetch the correct plural form for the selected language. diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index e322e3adc0..d95492479c 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -353,7 +353,7 @@ This controls the drop sections, i.e. the decision and drawing of possible drop locations based on the mouse position. </member> <member name="enable_recursive_folding" type="bool" setter="set_enable_recursive_folding" getter="is_recursive_folding_enabled" default="true"> - If [code]true[/code], recursive folding is enabled for this [Tree]. Holding down Shift while clicking the fold arrow collapses or uncollapses the [TreeItem] and all its descendants. + If [code]true[/code], recursive folding is enabled for this [Tree]. Holding down [kbd]Shift[/kbd] while clicking the fold arrow or using [code]ui_right[/code]/[code]ui_left[/code] shortcuts collapses or uncollapses the [TreeItem] and all its descendants. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> <member name="hide_folding" type="bool" setter="set_hide_folding" getter="is_folding_hidden" default="false"> @@ -414,7 +414,7 @@ </description> </signal> <signal name="empty_clicked"> - <param index="0" name="position" type="Vector2" /> + <param index="0" name="click_position" type="Vector2" /> <param index="1" name="mouse_button_index" type="int" /> <description> Emitted when a mouse button is clicked in the empty space of the tree. @@ -442,7 +442,7 @@ </description> </signal> <signal name="item_mouse_selected"> - <param index="0" name="position" type="Vector2" /> + <param index="0" name="mouse_position" type="Vector2" /> <param index="1" name="mouse_button_index" type="int" /> <description> Emitted when an item is selected with a mouse button. @@ -506,7 +506,10 @@ <theme_item name="font_color" data_type="color" type="Color" default="Color(0.7, 0.7, 0.7, 1)"> Default text [Color] of the item. </theme_item> - <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="font_disabled_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 0.5)"> + Text [Color] for a [constant TreeItem.CELL_MODE_CHECK] mode cell when it's non-editable (see [method TreeItem.set_editable]). + </theme_item> + <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The tint of text outline of the item. </theme_item> <theme_item name="font_selected_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> @@ -619,16 +622,25 @@ The arrow icon used when a foldable item is collapsed (for right-to-left layouts). </theme_item> <theme_item name="checked" data_type="icon" type="Texture2D"> - The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is checked. + The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is checked and editable (see [method TreeItem.set_editable]). + </theme_item> + <theme_item name="checked_disabled" data_type="icon" type="Texture2D"> + The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is checked and non-editable (see [method TreeItem.set_editable]). </theme_item> <theme_item name="indeterminate" data_type="icon" type="Texture2D"> - The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is indeterminate. + The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is indeterminate and editable (see [method TreeItem.set_editable]). + </theme_item> + <theme_item name="indeterminate_disabled" data_type="icon" type="Texture2D"> + The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is indeterminate and non-editable (see [method TreeItem.set_editable]). </theme_item> <theme_item name="select_arrow" data_type="icon" type="Texture2D"> The arrow icon to display for the [constant TreeItem.CELL_MODE_RANGE] mode cell. </theme_item> <theme_item name="unchecked" data_type="icon" type="Texture2D"> - The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is unchecked. + The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is unchecked and editable (see [method TreeItem.set_editable]). + </theme_item> + <theme_item name="unchecked_disabled" data_type="icon" type="Texture2D"> + The check icon to display when the [constant TreeItem.CELL_MODE_CHECK] mode cell is unchecked and non-editable (see [method TreeItem.set_editable]). </theme_item> <theme_item name="updown" data_type="icon" type="Texture2D"> The updown arrow icon to display for the [constant TreeItem.CELL_MODE_RANGE] mode cell. diff --git a/doc/classes/TreeItem.xml b/doc/classes/TreeItem.xml index 597a363514..c679838ec5 100644 --- a/doc/classes/TreeItem.xml +++ b/doc/classes/TreeItem.xml @@ -96,6 +96,14 @@ Returns the button index if there is a button with ID [param id] in column [param column], otherwise returns -1. </description> </method> + <method name="get_button_color" qualifiers="const"> + <return type="Color" /> + <param index="0" name="column" type="int" /> + <param index="1" name="id" type="int" /> + <description> + Returns the color of the button with ID [param id] in column [param column]. If the specified button does not exist, returns [constant Color.BLACK]. + </description> + </method> <method name="get_button_count" qualifiers="const"> <return type="int" /> <param index="0" name="column" type="int" /> @@ -160,6 +168,13 @@ Returns the custom color of column [param column]. </description> </method> + <method name="get_custom_draw_callback" qualifiers="const"> + <return type="Callable" /> + <param index="0" name="column" type="int" /> + <description> + Returns the custom callback of column [param column]. + </description> + </method> <method name="get_custom_font" qualifiers="const"> <return type="Font" /> <param index="0" name="column" type="int" /> @@ -423,6 +438,12 @@ Returns [code]true[/code] if the given [param column] is selected. </description> </method> + <method name="is_visible_in_tree" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if [member visible] is [code]true[/code] and all its ancestors are also visible. + </description> + </method> <method name="move_after"> <return type="void" /> <param index="0" name="item" type="TreeItem" /> @@ -553,13 +574,22 @@ Sets the given column's custom color. </description> </method> - <method name="set_custom_draw"> + <method name="set_custom_draw" deprecated="Use [method TreeItem.set_custom_draw_callback] instead."> <return type="void" /> <param index="0" name="column" type="int" /> <param index="1" name="object" type="Object" /> <param index="2" name="callback" type="StringName" /> <description> - Sets the given column's custom draw callback to [param callback] method on [param object]. + Sets the given column's custom draw callback to the [param callback] method on [param object]. + The method named [param callback] should accept two arguments: the [TreeItem] that is drawn and its position and size as a [Rect2]. + </description> + </method> + <method name="set_custom_draw_callback"> + <return type="void" /> + <param index="0" name="column" type="int" /> + <param index="1" name="callback" type="Callable" /> + <description> + Sets the given column's custom draw callback. Use an empty [Callable] ([code skip-lint]Callable()[/code]) to clear the custom callback. The [param callback] should accept two arguments: the [TreeItem] that is drawn and its position and size as a [Rect2]. </description> </method> @@ -754,6 +784,7 @@ <method name="uncollapse_tree"> <return type="void" /> <description> + Uncollapses all [TreeItem]s necessary to reveal this [TreeItem], i.e. all ancestor [TreeItem]s. </description> </method> </methods> diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml index 0ecfe53123..ac16bebecb 100644 --- a/doc/classes/Tween.xml +++ b/doc/classes/Tween.xml @@ -5,7 +5,7 @@ </brief_description> <description> Tweens are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name [i]tween[/i] comes from [i]in-betweening[/i], an animation technique where you specify [i]keyframes[/i] and the computer interpolates the frames that appear between them. Animating something with a [Tween] is called tweening. - [Tween] is more suited than [AnimationPlayer] for animations where you don't know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a [Tween]; it would be difficult to do the same thing with an [AnimationPlayer] node. Tweens are also more light-weight than [AnimationPlayer], so they are very much suited for simple animations or general tasks that don't require visual tweaking provided by the editor. They can be used in a fire-and-forget manner for some logic that normally would be done by code. You can e.g. make something shoot periodically by using a looped [CallbackTweener] with a delay. + [Tween] is more suited than [AnimationPlayer] for animations where you don't know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a [Tween]; it would be difficult to do the same thing with an [AnimationPlayer] node. Tweens are also more light-weight than [AnimationPlayer], so they are very much suited for simple animations or general tasks that don't require visual tweaking provided by the editor. They can be used in a "fire-and-forget" manner for some logic that normally would be done by code. You can e.g. make something shoot periodically by using a looped [CallbackTweener] with a delay. A [Tween] can be created by using either [method SceneTree.create_tween] or [method Node.create_tween]. [Tween]s created manually (i.e. by using [code]Tween.new()[/code]) are invalid and can't be used for tweening values. A tween animation is created by adding [Tweener]s to the [Tween] object, using [method tween_property], [method tween_interval], [method tween_callback] or [method tween_method]: [codeblocks] @@ -237,6 +237,12 @@ <param index="0" name="parallel" type="bool" default="true" /> <description> If [param parallel] is [code]true[/code], the [Tweener]s appended after this method will by default run simultaneously, as opposed to sequentially. + [b]Note:[/b] Just like with [method parallel], the tweener added right before this method will also be part of the parallel step. + [codeblock] + tween.tween_property(self, "position", Vector2(300, 0), 0.5) + tween.set_parallel() + tween.tween_property(self, "modulate", Color.GREEN, 0.5) # Runs together with the position tweener. + [/codeblock] </description> </method> <method name="set_pause_mode"> diff --git a/doc/classes/UndoRedo.xml b/doc/classes/UndoRedo.xml index 50414d2580..e197f7748c 100644 --- a/doc/classes/UndoRedo.xml +++ b/doc/classes/UndoRedo.xml @@ -112,7 +112,8 @@ <return type="void" /> <param index="0" name="object" type="Object" /> <description> - Register a reference for "do" that will be erased if the "do" history is lost. This is useful mostly for new nodes created for the "do" call. Do not use for resources. + Register a reference to an object that will be erased if the "do" history is deleted. This is useful for objects added by the "do" action and removed by the "undo" action. + When the "do" history is deleted, if the object is a [RefCounted], it will be unreferenced. Otherwise, it will be freed. Do not use for resources. [codeblock] var node = Node2D.new() undo_redo.create_action("Add node") @@ -143,7 +144,8 @@ <return type="void" /> <param index="0" name="object" type="Object" /> <description> - Register a reference for "undo" that will be erased if the "undo" history is lost. This is useful mostly for nodes removed with the "do" call (not the "undo" call!). + Register a reference to an object that will be erased if the "undo" history is deleted. This is useful for objects added by the "undo" action and removed by the "do" action. + When the "undo" history is deleted, if the object is a [RefCounted], it will be unreferenced. Otherwise, it will be freed. Do not use for resources. [codeblock] var node = $Node2D undo_redo.create_action("Remove node") @@ -255,6 +257,11 @@ </description> </method> </methods> + <members> + <member name="max_steps" type="int" setter="set_max_steps" getter="get_max_steps" default="0"> + The maximum number of steps that can be stored in the undo/redo history. If the number of stored steps exceeds this limit, older steps are removed from history and can no longer be reached by calling [method undo]. A value of [code]0[/code] or lower means no limit. + </member> + </members> <signals> <signal name="version_changed"> <description> @@ -267,10 +274,10 @@ Makes "do"/"undo" operations stay in separate actions. </constant> <constant name="MERGE_ENDS" value="1" enum="MergeMode"> - Makes so that the action's "undo" operations are from the first action created and the "do" operations are from the last subsequent action with the same name. + Merges this action with the previous one if they have the same name. Keeps only the first action's "undo" operations and the last action's "do" operations. Useful for sequential changes to a single value. </constant> <constant name="MERGE_ALL" value="2" enum="MergeMode"> - Makes subsequent actions with the same name be merged into one. + Merges this action with the previous one if they have the same name. </constant> </constants> </class> diff --git a/doc/classes/UniformSetCacheRD.xml b/doc/classes/UniformSetCacheRD.xml new file mode 100644 index 0000000000..32e516c295 --- /dev/null +++ b/doc/classes/UniformSetCacheRD.xml @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="UniformSetCacheRD" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + Uniform set cache manager for Rendering Device based renderers. + </brief_description> + <description> + Uniform set cache manager for Rendering Device based renderers. Provides a way to create a uniform set and reuse it in subsequent calls for as long as the uniform set exists. Uniform set will automatically be cleaned up when dependent objects are freed. + </description> + <tutorials> + </tutorials> + <methods> + <method name="get_cache" qualifiers="static"> + <return type="RID" /> + <param index="0" name="shader" type="RID" /> + <param index="1" name="set" type="int" /> + <param index="2" name="uniforms" type="RDUniform[]" /> + <description> + Creates/returns a cached uniform set based on the provided uniforms for a given shader. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/Variant.xml b/doc/classes/Variant.xml index 2734800642..eb837a4643 100644 --- a/doc/classes/Variant.xml +++ b/doc/classes/Variant.xml @@ -11,7 +11,7 @@ foo = "Now foo is a string!" foo = RefCounted.new() # foo is an Object var bar: int = 2 # bar is a statically typed integer. - # bar = "Uh oh! I can't make static variables become a different type!" + # bar = "Uh oh! I can't make statically typed variables become a different type!" [/gdscript] [csharp] // C# is statically typed. Once a variable has a type it cannot be changed. You can use the `var` keyword to let the compiler infer the type automatically. @@ -36,7 +36,7 @@ match typeof(foo): TYPE_NIL: print("foo is null") - TYPE_INTEGER: + TYPE_INT: print("foo is an integer") TYPE_OBJECT: # Note that Objects are their own special category. diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml index 3fa7bb46fc..f33076a92f 100644 --- a/doc/classes/Vector2.xml +++ b/doc/classes/Vector2.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Vector2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - A 2D vector using floating point coordinates. + A 2D vector using floating-point coordinates. </brief_description> <description> A 2-element structure that can be used to represent 2D coordinates or any other pair of numeric values. @@ -236,7 +236,7 @@ This method is faster than using [method is_equal_approx] with one value as a zero vector. </description> </method> - <method name="length" qualifiers="const"> + <method name="length" qualifiers="const" keywords="size"> <return type="float" /> <description> Returns the length (magnitude) of this vector. @@ -249,7 +249,7 @@ This method runs faster than [method length], so prefer it if you need to compare vectors or need the squared distance for some formula. </description> </method> - <method name="lerp" qualifiers="const"> + <method name="lerp" qualifiers="const" keywords="interpolate"> <return type="Vector2" /> <param index="0" name="to" type="Vector2" /> <param index="1" name="weight" type="float" /> @@ -257,7 +257,7 @@ Returns the result of the linear interpolation between this vector and [param to] by amount [param weight]. [param weight] is on the range of [code]0.0[/code] to [code]1.0[/code], representing the amount of interpolation. </description> </method> - <method name="limit_length" qualifiers="const"> + <method name="limit_length" qualifiers="const" keywords="truncate"> <return type="Vector2" /> <param index="0" name="length" type="float" default="1.0" /> <description> @@ -315,7 +315,8 @@ <return type="Vector2" /> <param index="0" name="b" type="Vector2" /> <description> - Returns the result of projecting the vector onto the given vector [param b]. + Returns a new vector resulting from projecting this vector onto the given vector [param b]. The resulting new vector is parallel to [param b]. See also [method slide]. + [b]Note:[/b] If the vector [param b] is a zero vector, the components of the resulting new vector will be [constant @GDScript.NAN]. </description> </method> <method name="reflect" qualifiers="const"> @@ -344,7 +345,7 @@ Returns a new vector with each component set to [code]1.0[/code] if it's positive, [code]-1.0[/code] if it's negative, and [code]0.0[/code] if it's zero. The result is identical to calling [method @GlobalScope.sign] on each component. </description> </method> - <method name="slerp" qualifiers="const"> + <method name="slerp" qualifiers="const" keywords="interpolate"> <return type="Vector2" /> <param index="0" name="to" type="Vector2" /> <param index="1" name="weight" type="float" /> @@ -357,7 +358,8 @@ <return type="Vector2" /> <param index="0" name="n" type="Vector2" /> <description> - Returns the result of sliding the vector along a plane defined by the given normal. + Returns a new vector resulting from sliding this vector along a line with normal [param n]. The resulting new vector is perpendicular to [param n], and is equivalent to this vector minus its projection on [param n]. See also [method project]. + [b]Note:[/b] The vector [param n] must be normalized. See also [method normalized]. </description> </method> <method name="snapped" qualifiers="const"> diff --git a/doc/classes/Vector2i.xml b/doc/classes/Vector2i.xml index 2100cd7612..18291e06a9 100644 --- a/doc/classes/Vector2i.xml +++ b/doc/classes/Vector2i.xml @@ -64,7 +64,22 @@ Returns a new vector with all components clamped between the components of [param min] and [param max], by running [method @GlobalScope.clamp] on each component. </description> </method> - <method name="length" qualifiers="const"> + <method name="distance_squared_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="Vector2i" /> + <description> + Returns the squared distance between this vector and [param to]. + This method runs faster than [method distance_to], so prefer it if you need to compare vectors or need the squared distance for some formula. + </description> + </method> + <method name="distance_to" qualifiers="const"> + <return type="float" /> + <param index="0" name="to" type="Vector2i" /> + <description> + Returns the distance between this vector and [param to]. + </description> + </method> + <method name="length" qualifiers="const" keywords="size"> <return type="float" /> <description> Returns the length (magnitude) of this vector. diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml index 83a8c6af73..872534fd89 100644 --- a/doc/classes/Vector3.xml +++ b/doc/classes/Vector3.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Vector3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - A 3D vector using floating point coordinates. + A 3D vector using floating-point coordinates. </brief_description> <description> A 3-element structure that can be used to represent 3D coordinates or any other triplet of numeric values. @@ -204,7 +204,7 @@ This method is faster than using [method is_equal_approx] with one value as a zero vector. </description> </method> - <method name="length" qualifiers="const"> + <method name="length" qualifiers="const" keywords="size"> <return type="float" /> <description> Returns the length (magnitude) of this vector. @@ -217,7 +217,7 @@ This method runs faster than [method length], so prefer it if you need to compare vectors or need the squared distance for some formula. </description> </method> - <method name="lerp" qualifiers="const"> + <method name="lerp" qualifiers="const" keywords="interpolate"> <return type="Vector3" /> <param index="0" name="to" type="Vector3" /> <param index="1" name="weight" type="float" /> @@ -225,7 +225,7 @@ Returns the result of the linear interpolation between this vector and [param to] by amount [param weight]. [param weight] is on the range of [code]0.0[/code] to [code]1.0[/code], representing the amount of interpolation. </description> </method> - <method name="limit_length" qualifiers="const"> + <method name="limit_length" qualifiers="const" keywords="truncate"> <return type="Vector3" /> <param index="0" name="length" type="float" default="1.0" /> <description> @@ -299,7 +299,8 @@ <return type="Vector3" /> <param index="0" name="b" type="Vector3" /> <description> - Returns the result of projecting the vector onto the given vector [param b]. + Returns a new vector resulting from projecting this vector onto the given vector [param b]. The resulting new vector is parallel to [param b]. See also [method slide]. + [b]Note:[/b] If the vector [param b] is a zero vector, the components of the resulting new vector will be [constant @GDScript.NAN]. </description> </method> <method name="reflect" qualifiers="const"> @@ -337,7 +338,7 @@ Returns the signed angle to the given vector, in radians. The sign of the angle is positive in a counter-clockwise direction and negative in a clockwise direction when viewed from the side specified by the [param axis]. </description> </method> - <method name="slerp" qualifiers="const"> + <method name="slerp" qualifiers="const" keywords="interpolate"> <return type="Vector3" /> <param index="0" name="to" type="Vector3" /> <param index="1" name="weight" type="float" /> @@ -350,7 +351,8 @@ <return type="Vector3" /> <param index="0" name="n" type="Vector3" /> <description> - Returns a new vector slid along a plane defined by the given normal. + Returns a new vector resulting from sliding this vector along a plane with normal [param n]. The resulting new vector is perpendicular to [param n], and is equivalent to this vector minus its projection on [param n]. See also [method project]. + [b]Note:[/b] The vector [param n] must be normalized. See also [method normalized]. </description> </method> <method name="snapped" qualifiers="const"> diff --git a/doc/classes/Vector3i.xml b/doc/classes/Vector3i.xml index 8906bf0aa7..ffebd3e1f3 100644 --- a/doc/classes/Vector3i.xml +++ b/doc/classes/Vector3i.xml @@ -59,7 +59,22 @@ Returns a new vector with all components clamped between the components of [param min] and [param max], by running [method @GlobalScope.clamp] on each component. </description> </method> - <method name="length" qualifiers="const"> + <method name="distance_squared_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="Vector3i" /> + <description> + Returns the squared distance between this vector and [param to]. + This method runs faster than [method distance_to], so prefer it if you need to compare vectors or need the squared distance for some formula. + </description> + </method> + <method name="distance_to" qualifiers="const"> + <return type="float" /> + <param index="0" name="to" type="Vector3i" /> + <description> + Returns the distance between this vector and [param to]. + </description> + </method> + <method name="length" qualifiers="const" keywords="size"> <return type="float" /> <description> Returns the length (magnitude) of this vector. diff --git a/doc/classes/Vector4.xml b/doc/classes/Vector4.xml index c5503a9357..b31cdb01c9 100644 --- a/doc/classes/Vector4.xml +++ b/doc/classes/Vector4.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Vector4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - A 4D vector using floating point coordinates. + A 4D vector using floating-point coordinates. </brief_description> <description> A 4-element structure that can be used to represent 4D coordinates or any other quadruplet of numeric values. @@ -155,7 +155,7 @@ This method is faster than using [method is_equal_approx] with one value as a zero vector. </description> </method> - <method name="length" qualifiers="const"> + <method name="length" qualifiers="const" keywords="size"> <return type="float" /> <description> Returns the length (magnitude) of this vector. @@ -168,7 +168,7 @@ This method runs faster than [method length], so prefer it if you need to compare vectors or need the squared distance for some formula. </description> </method> - <method name="lerp" qualifiers="const"> + <method name="lerp" qualifiers="const" keywords="interpolate"> <return type="Vector4" /> <param index="0" name="to" type="Vector4" /> <param index="1" name="weight" type="float" /> diff --git a/doc/classes/Vector4i.xml b/doc/classes/Vector4i.xml index a612c135dd..f8a0026066 100644 --- a/doc/classes/Vector4i.xml +++ b/doc/classes/Vector4i.xml @@ -6,7 +6,7 @@ <description> A 4-element structure that can be used to represent 4D grid coordinates or any other quadruplet of integers. It uses integer coordinates and is therefore preferable to [Vector4] when exact precision is required. Note that the values are limited to 32 bits, and unlike [Vector4] this cannot be configured with an engine build option. Use [int] or [PackedInt64Array] if 64-bit values are needed. - [b]Note:[/b] In a boolean context, a Vector4i will evaluate to [code]false[/code] if it's equal to [code]Vector4i(0, 0, 0, 0)[/code]. Otherwise, a Vector3i will always evaluate to [code]true[/code]. + [b]Note:[/b] In a boolean context, a Vector4i will evaluate to [code]false[/code] if it's equal to [code]Vector4i(0, 0, 0, 0)[/code]. Otherwise, a Vector4i will always evaluate to [code]true[/code]. </description> <tutorials> </tutorials> @@ -57,7 +57,22 @@ Returns a new vector with all components clamped between the components of [param min] and [param max], by running [method @GlobalScope.clamp] on each component. </description> </method> - <method name="length" qualifiers="const"> + <method name="distance_squared_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="Vector4i" /> + <description> + Returns the squared distance between this vector and [param to]. + This method runs faster than [method distance_to], so prefer it if you need to compare vectors or need the squared distance for some formula. + </description> + </method> + <method name="distance_to" qualifiers="const"> + <return type="float" /> + <param index="0" name="to" type="Vector4i" /> + <description> + Returns the distance between this vector and [param to]. + </description> + </method> + <method name="length" qualifiers="const" keywords="size"> <return type="float" /> <description> Returns the length (magnitude) of this vector. diff --git a/doc/classes/VehicleWheel3D.xml b/doc/classes/VehicleWheel3D.xml index 9c7ba58534..77cb5ca9f8 100644 --- a/doc/classes/VehicleWheel3D.xml +++ b/doc/classes/VehicleWheel3D.xml @@ -81,7 +81,7 @@ This is the distance in meters the wheel is lowered from its origin point. Don't set this to 0.0 and move the wheel into position, instead move the origin point of your wheel (the gizmo in Godot) to the position the wheel will take when bottoming out, then use the rest length to move the wheel down to the position it should be in when the car is in rest. </member> <member name="wheel_roll_influence" type="float" setter="set_roll_influence" getter="get_roll_influence" default="0.1"> - This value affects the roll of your vehicle. If set to 1.0 for all wheels, your vehicle will be prone to rolling over, while a value of 0.0 will resist body roll. + This value affects the roll of your vehicle. If set to 1.0 for all wheels, your vehicle will resist body roll, while a value of 0.0 will be prone to rolling over. </member> </members> </class> diff --git a/doc/classes/VideoStream.xml b/doc/classes/VideoStream.xml index aa4c91bac2..271330a598 100644 --- a/doc/classes/VideoStream.xml +++ b/doc/classes/VideoStream.xml @@ -8,6 +8,7 @@ </description> <tutorials> <link title="Playing videos">$DOCS_URL/tutorials/animation/playing_videos.html</link> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="_instantiate_playback" qualifiers="virtual"> diff --git a/doc/classes/VideoStreamPlayer.xml b/doc/classes/VideoStreamPlayer.xml index 0d8776b0b7..f903f171d1 100644 --- a/doc/classes/VideoStreamPlayer.xml +++ b/doc/classes/VideoStreamPlayer.xml @@ -6,7 +6,6 @@ <description> A control used for playback of [VideoStream] resources. Supported video formats are [url=https://www.theora.org/]Ogg Theora[/url] ([code].ogv[/code], [VideoStreamTheora]) and any format exposed via a GDExtension plugin. - [b]Note:[/b] Due to a bug, VideoStreamPlayer does not support localization remapping yet. [b]Warning:[/b] On Web, video playback [i]will[/i] perform poorly due to missing architecture-specific assembly optimizations. </description> <tutorials> diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 1b5f7148ac..dcc817427b 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -4,7 +4,7 @@ Abstract base class for viewports. Encapsulates drawing and interaction with a game world. </brief_description> <description> - A Viewport creates a different view into the screen, or a sub-view inside another viewport. Children 2D Nodes will display on it, and children Camera3D 3D nodes will render on it too. + A [Viewport] creates a different view into the screen, or a sub-view inside another viewport. Child 2D nodes will display on it, and child Camera3D 3D nodes will render on it too. Optionally, a viewport can have its own 2D or 3D world, so it doesn't share what it draws with other viewports. Viewports can also choose to be audio listeners, so they generate positional audio depending on a 2D or 3D camera child of it. Also, viewports can be assigned to different screens in case the devices have multiple screens. @@ -75,7 +75,7 @@ <return type="int" enum="Viewport.PositionalShadowAtlasQuadrantSubdiv" /> <param index="0" name="quadrant" type="int" /> <description> - Returns the [enum PositionalShadowAtlasQuadrantSubdiv] of the specified quadrant. + Returns the positional shadow atlas quadrant subdivision of the specified quadrant. </description> </method> <method name="get_render_info"> @@ -128,6 +128,13 @@ Returns the [Control] having the focus within this viewport. If no [Control] has the focus, returns null. </description> </method> + <method name="gui_get_hovered_control" qualifiers="const"> + <return type="Control" /> + <description> + Returns the [Control] that the mouse is currently hovering over in this viewport. If no [Control] has the cursor, returns null. + Typically the leaf [Control] node or deepest level of the subtree which claims hover. This is very useful when used together with [method Node.is_ancestor_of] to find if the mouse is within a control tree. + </description> + </method> <method name="gui_is_drag_successful" qualifiers="const"> <return type="bool" /> <description> @@ -180,14 +187,13 @@ Helper method which calls the [code]set_text()[/code] method on the currently focused [Control], provided that it is defined (e.g. if the focused Control is [Button] or [LineEdit]). </description> </method> - <method name="push_unhandled_input" is_deprecated="true"> + <method name="push_unhandled_input" deprecated="Use [method push_input] instead."> <return type="void" /> <param index="0" name="event" type="InputEvent" /> <param index="1" name="in_local_coords" type="bool" default="false" /> <description> - Triggers the given [InputEvent] in this [Viewport]. This can be used to pass input events between viewports, or to locally apply inputs that were sent over the network or saved to a file. + Triggers the given [param event] in this [Viewport]. This can be used to pass an [InputEvent] between viewports, or to locally apply inputs that were sent over the network or saved to a file. If [param in_local_coords] is [code]false[/code], the event's position is in the embedder's coordinates and will be converted to viewport coordinates. If [param in_local_coords] is [code]true[/code], the event's position is in viewport coordinates. - While this method serves a similar purpose as [method Input.parse_input_event], it does not remap the specified [param event] based on project settings like [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse]. Calling this method will propagate calls to child nodes for following methods in the given order: - [method Node._shortcut_input] - [method Node._unhandled_key_input] @@ -195,7 +201,6 @@ If an earlier method marks the input as handled via [method set_input_as_handled], any later method in this list will not be called. If none of the methods handle the event and [member physics_object_picking] is [code]true[/code], the event is used for physics object picking. [b]Note:[/b] This method doesn't propagate input events to embedded [Window]s or [SubViewport]s. - [i]Deprecated.[/i] Use [method push_input] instead. </description> </method> <method name="set_canvas_cull_mask_bit"> @@ -300,6 +305,11 @@ If [code]true[/code], the objects rendered by viewport become subjects of mouse picking process. [b]Note:[/b] The number of simultaneously pickable objects is limited to 64 and they are selected in a non-deterministic order, which can be different in each picking process. </member> + <member name="physics_object_picking_first_only" type="bool" setter="set_physics_object_picking_first_only" getter="get_physics_object_picking_first_only" default="false"> + If [code]true[/code], the input_event signal will only be sent to one physics object in the mouse picking process. If you want to get the top object only, you must also enable [member physics_object_picking_sort]. + If [code]false[/code], an input_event signal will be sent to all physics objects in the mouse picking process. + This applies to 2D CanvasItem object picking only. + </member> <member name="physics_object_picking_sort" type="bool" setter="set_physics_object_picking_sort" getter="get_physics_object_picking_sort" default="false"> If [code]true[/code], objects receive mouse picking events sorted primarily by their [member CanvasItem.z_index] and secondarily by their position in the scene tree. If [code]false[/code], the order is undetermined. [b]Note:[/b] This setting is disabled by default because of its potential expensive computational cost. @@ -358,7 +368,7 @@ In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. </member> <member name="use_hdr_2d" type="bool" setter="set_use_hdr_2d" getter="is_using_hdr_2d" default="false"> - If [code]true[/code], 2D rendering will use an high dynamic range (HDR) format framebuffer matching the bit depth of the 3D framebuffer. When using the Forward+ renderer this will be a [code]RGBA16[/code] framebuffer, while when using the Mobile renderer it will be a [code]RGB10_A2[/code] framebuffer. Additionally, 2D rendering will take place in linear color space and will be converted to sRGB space immediately before blitting to the screen (if the Viewport is attached to the screen). Practically speaking, this means that the end result of the Viewport will not be clamped into the [code]0-1[/code] range and can be used in 3D rendering without color space adjustments. This allows 2D rendering to take advantage of effects requiring high dynamic range (e.g. 2D glow) as well as substantially improves the appearance of effects requiring highly detailed gradients. + If [code]true[/code], 2D rendering will use an high dynamic range (HDR) format framebuffer matching the bit depth of the 3D framebuffer. When using the Forward+ renderer this will be an [code]RGBA16[/code] framebuffer, while when using the Mobile renderer it will be an [code]RGB10_A2[/code] framebuffer. Additionally, 2D rendering will take place in linear color space and will be converted to sRGB space immediately before blitting to the screen (if the Viewport is attached to the screen). Practically speaking, this means that the end result of the Viewport will not be clamped into the [code]0-1[/code] range and can be used in 3D rendering without color space adjustments. This allows 2D rendering to take advantage of effects requiring high dynamic range (e.g. 2D glow) as well as substantially improves the appearance of effects requiring highly detailed gradients. [b]Note:[/b] This setting will have no effect when using the GL Compatibility renderer as the GL Compatibility renderer always renders in low dynamic range for performance reasons. </member> <member name="use_occlusion_culling" type="bool" setter="set_use_occlusion_culling" getter="is_using_occlusion_culling" default="false"> @@ -380,16 +390,16 @@ Texture to use when [member vrs_mode] is set to [constant Viewport.VRS_TEXTURE]. The texture [i]must[/i] use a lossless compression format so that colors can be matched precisely. The following VRS densities are mapped to various colors, with brighter colors representing a lower level of shading precision: [codeblock] - - 1x1 = rgb(0, 0, 0) - #000000 - - 1x2 = rgb(0, 85, 0) - #005500 - - 2x1 = rgb(85, 0, 0) - #550000 - - 2x2 = rgb(85, 85, 0) - #555500 - - 2x4 = rgb(85, 170, 0) - #55aa00 - - 4x2 = rgb(170, 85, 0) - #aa5500 - - 4x4 = rgb(170, 170, 0) - #aaaa00 - - 4x8 = rgb(170, 255, 0) - #aaff00 - Not supported on most hardware - - 8x4 = rgb(255, 170, 0) - #ffaa00 - Not supported on most hardware - - 8x8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware + - 1×1 = rgb(0, 0, 0) - #000000 + - 1×2 = rgb(0, 85, 0) - #005500 + - 2×1 = rgb(85, 0, 0) - #550000 + - 2×2 = rgb(85, 85, 0) - #555500 + - 2×4 = rgb(85, 170, 0) - #55aa00 + - 4×2 = rgb(170, 85, 0) - #aa5500 + - 4×4 = rgb(170, 170, 0) - #aaaa00 + - 4×8 = rgb(170, 255, 0) - #aaff00 - Not supported on most hardware + - 8×4 = rgb(255, 170, 0) - #ffaa00 - Not supported on most hardware + - 8×8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware [/codeblock] </member> <member name="world_2d" type="World2D" setter="set_world_2d" getter="get_world_2d"> @@ -404,6 +414,7 @@ <param index="0" name="node" type="Control" /> <description> Emitted when a Control node grabs keyboard focus. + [b]Note:[/b] A Control node losing focus doesn't cause this signal to be emitted. </description> </signal> <signal name="size_changed"> @@ -486,10 +497,16 @@ Represents the size of the [enum RenderInfo] enum. </constant> <constant name="RENDER_INFO_TYPE_VISIBLE" value="0" enum="RenderInfoType"> + Visible render pass (excluding shadows). </constant> <constant name="RENDER_INFO_TYPE_SHADOW" value="1" enum="RenderInfoType"> + Shadow render pass. Objects will be rendered several times depending on the number of amounts of lights with shadows and the number of directional shadow splits. + </constant> + <constant name="RENDER_INFO_TYPE_CANVAS" value="2" enum="RenderInfoType"> + Canvas item rendering. This includes all 2D rendering. </constant> - <constant name="RENDER_INFO_TYPE_MAX" value="2" enum="RenderInfoType"> + <constant name="RENDER_INFO_TYPE_MAX" value="3" enum="RenderInfoType"> + Represents the size of the [enum RenderInfoType] enum. </constant> <constant name="DEBUG_DRAW_DISABLED" value="0" enum="DebugDraw"> Objects are displayed normally. @@ -560,16 +577,18 @@ Draws the internal resolution buffer of the scene before post-processing is applied. </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST" value="0" enum="DefaultCanvasItemTextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR" value="1" enum="DefaultCanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="2" enum="DefaultCanvasItemTextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="3" enum="DefaultCanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_MAX" value="4" enum="DefaultCanvasItemTextureFilter"> Max value for [enum DefaultCanvasItemTextureFilter] enum. diff --git a/doc/classes/VisibleOnScreenEnabler2D.xml b/doc/classes/VisibleOnScreenEnabler2D.xml index e9017a389b..75987fa21c 100644 --- a/doc/classes/VisibleOnScreenEnabler2D.xml +++ b/doc/classes/VisibleOnScreenEnabler2D.xml @@ -15,7 +15,7 @@ Determines how the target node is enabled. Corresponds to [enum Node.ProcessMode]. When the node is disabled, it always uses [constant Node.PROCESS_MODE_DISABLED]. </member> <member name="enable_node_path" type="NodePath" setter="set_enable_node_path" getter="get_enable_node_path" default="NodePath("..")"> - The path to the target node, relative to the [VisibleOnScreenEnabler2D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler2D] is inside the scene tree) and every time the [VisibleOnScreenEnabler2D] enters the scene tree. If the path is invalid, an error will be printed in the editor and no node will be affected. + The path to the target node, relative to the [VisibleOnScreenEnabler2D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler2D] is inside the scene tree) and every time the [VisibleOnScreenEnabler2D] enters the scene tree. If the path is empty, no node will be affected. If the path is invalid, an error is also generated. </member> </members> <constants> diff --git a/doc/classes/VisibleOnScreenEnabler3D.xml b/doc/classes/VisibleOnScreenEnabler3D.xml index a26a47ac92..ff7547f75b 100644 --- a/doc/classes/VisibleOnScreenEnabler3D.xml +++ b/doc/classes/VisibleOnScreenEnabler3D.xml @@ -15,7 +15,7 @@ Determines how the target node is enabled. Corresponds to [enum Node.ProcessMode]. When the node is disabled, it always uses [constant Node.PROCESS_MODE_DISABLED]. </member> <member name="enable_node_path" type="NodePath" setter="set_enable_node_path" getter="get_enable_node_path" default="NodePath("..")"> - The path to the target node, relative to the [VisibleOnScreenEnabler3D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler3D] is inside the scene tree) and every time the [VisibleOnScreenEnabler3D] enters the scene tree. If the path is invalid, an error will be printed in the editor and no node will be affected. + The path to the target node, relative to the [VisibleOnScreenEnabler3D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler3D] is inside the scene tree) and every time the [VisibleOnScreenEnabler3D] enters the scene tree. If the path is empty, no node will be affected. If the path is invalid, an error is also generated. </member> </members> <constants> diff --git a/doc/classes/VisualShader.xml b/doc/classes/VisualShader.xml index f424a27a8f..c8230d94e4 100644 --- a/doc/classes/VisualShader.xml +++ b/doc/classes/VisualShader.xml @@ -29,6 +29,15 @@ Adds a new varying value node to the shader. </description> </method> + <method name="attach_node_to_frame"> + <return type="void" /> + <param index="0" name="type" type="int" enum="VisualShader.Type" /> + <param index="1" name="id" type="int" /> + <param index="2" name="frame" type="int" /> + <description> + Attaches the given node to the given frame. + </description> + </method> <method name="can_connect_nodes" qualifiers="const"> <return type="bool" /> <param index="0" name="type" type="int" enum="VisualShader.Type" /> @@ -62,6 +71,14 @@ Connects the specified nodes and ports, even if they can't be connected. Such connection is invalid and will not function properly. </description> </method> + <method name="detach_node_from_frame"> + <return type="void" /> + <param index="0" name="type" type="int" enum="VisualShader.Type" /> + <param index="1" name="id" type="int" /> + <description> + Detaches the given node from the frame it is attached to. + </description> + </method> <method name="disconnect_nodes"> <return type="void" /> <param index="0" name="type" type="int" enum="VisualShader.Type" /> @@ -245,10 +262,10 @@ Represents the size of the [enum VaryingType] enum. </constant> <constant name="NODE_ID_INVALID" value="-1"> - Denotes invalid [VisualShader] node. + Indicates an invalid [VisualShader] node. </constant> <constant name="NODE_ID_OUTPUT" value="0"> - Denotes output node of [VisualShader]. + Indicates an output node of [VisualShader]. </constant> </constants> </class> diff --git a/doc/classes/VisualShaderNode.xml b/doc/classes/VisualShaderNode.xml index cc6394e2da..5b82d20246 100644 --- a/doc/classes/VisualShaderNode.xml +++ b/doc/classes/VisualShaderNode.xml @@ -61,6 +61,9 @@ </method> </methods> <members> + <member name="linked_parent_graph_frame" type="int" setter="set_frame" getter="get_frame" default="-1"> + Represents the index of the frame this node is linked to. If set to [code]-1[/code] the node is not linked to any frame. + </member> <member name="output_port_for_preview" type="int" setter="set_output_port_for_preview" getter="get_output_port_for_preview" default="-1"> Sets the output port index which will be showed for preview. If set to [code]-1[/code] no port will be open for preview. </member> diff --git a/doc/classes/VisualShaderNodeComment.xml b/doc/classes/VisualShaderNodeComment.xml deleted file mode 100644 index b4063409b9..0000000000 --- a/doc/classes/VisualShaderNodeComment.xml +++ /dev/null @@ -1,19 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" ?> -<class name="VisualShaderNodeComment" inherits="VisualShaderNodeResizableBase" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> - <brief_description> - A comment node to be placed on visual shader graph. - </brief_description> - <description> - A resizable rectangular area with changeable [member title] and [member description] used for better organizing of other visual shader nodes. - </description> - <tutorials> - </tutorials> - <members> - <member name="description" type="String" setter="set_description" getter="get_description" default=""""> - An additional description which placed below the title. - </member> - <member name="title" type="String" setter="set_title" getter="get_title" default=""Comment""> - A title of the node. - </member> - </members> -</class> diff --git a/doc/classes/VisualShaderNodeCubemap.xml b/doc/classes/VisualShaderNodeCubemap.xml index 8fc98e24cc..4e6cf2120a 100644 --- a/doc/classes/VisualShaderNodeCubemap.xml +++ b/doc/classes/VisualShaderNodeCubemap.xml @@ -33,7 +33,7 @@ No hints are added to the uniform declaration. </constant> <constant name="TYPE_COLOR" value="1" enum="TextureType"> - Adds [code]hint_albedo[/code] as hint to the uniform declaration for proper sRGB to linear conversion. + Adds [code]source_color[/code] as hint to the uniform declaration for proper sRGB to linear conversion. </constant> <constant name="TYPE_NORMAL_MAP" value="2" enum="TextureType"> Adds [code]hint_normal[/code] as hint to the uniform declaration, which internally converts the texture for proper usage as normal map. diff --git a/doc/classes/VisualShaderNodeFrame.xml b/doc/classes/VisualShaderNodeFrame.xml new file mode 100644 index 0000000000..3126a56abe --- /dev/null +++ b/doc/classes/VisualShaderNodeFrame.xml @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="VisualShaderNodeFrame" inherits="VisualShaderNodeResizableBase" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A frame other visual shader nodes can be attached to for better organization. + </brief_description> + <description> + A rectangular frame that can be used to group visual shader nodes together to improve organization. + Nodes attached to the frame will move with it when it is dragged and it can automatically resize to enclose all attached nodes. + Its title, description and color can be customized. + </description> + <tutorials> + </tutorials> + <methods> + <method name="add_attached_node"> + <return type="void" /> + <param index="0" name="node" type="int" /> + <description> + Adds a node to the list of nodes attached to the frame. Should not be called directly, use the [method VisualShader.attach_node_to_frame] method instead. + </description> + </method> + <method name="remove_attached_node"> + <return type="void" /> + <param index="0" name="node" type="int" /> + <description> + Removes a node from the list of nodes attached to the frame. Should not be called directly, use the [method VisualShader.detach_node_from_frame] method instead. + </description> + </method> + </methods> + <members> + <member name="attached_nodes" type="PackedInt32Array" setter="set_attached_nodes" getter="get_attached_nodes" default="PackedInt32Array()"> + The list of nodes attached to the frame. + </member> + <member name="autoshrink" type="bool" setter="set_autoshrink_enabled" getter="is_autoshrink_enabled" default="true"> + If [code]true[/code], the frame will automatically resize to enclose all attached nodes. + </member> + <member name="tint_color" type="Color" setter="set_tint_color" getter="get_tint_color" default="Color(0.3, 0.3, 0.3, 0.75)"> + The color of the frame when [member tint_color_enabled] is [code]true[/code]. + </member> + <member name="tint_color_enabled" type="bool" setter="set_tint_color_enabled" getter="is_tint_color_enabled" default="false"> + If [code]true[/code], the frame will be tinted with the color specified in [member tint_color]. + </member> + <member name="title" type="String" setter="set_title" getter="get_title" default=""Title""> + The title of the node. + </member> + </members> +</class> diff --git a/doc/classes/VisualShaderNodeIf.xml b/doc/classes/VisualShaderNodeIf.xml index 82799bb5fd..f3d76a4ac3 100644 --- a/doc/classes/VisualShaderNodeIf.xml +++ b/doc/classes/VisualShaderNodeIf.xml @@ -1,10 +1,13 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="VisualShaderNodeIf" inherits="VisualShaderNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Outputs a 3D vector based on the result of a floating point comparison within the visual shader graph. + Outputs a 3D vector based on the result of a floating-point comparison within the visual shader graph. </brief_description> <description> - This visual shader node has six input ports. Port 1 and 2 provide the two floating point numbers [code]a[/code] and [code]b[/code] that will be compared. Port 3 is the tolerance, which allows similar floating point number to be considered equal. Ports 4 to 6 are the possible outputs, returned if [code]a == b[/code], [code]a > b[/code], or [code]a < b[/code] respectively. + This visual shader node has six input ports: + - Port [b]1[/b] and [b]2[/b] provide the two floating-point numbers [code]a[/code] and [code]b[/code] that will be compared. + - Port [b]3[/b] is the tolerance, which allows similar floating-point numbers to be considered equal. + - Ports [b]4[/b], [b]5[/b], and [b]6[/b] are the possible outputs, returned if [code]a == b[/code], [code]a > b[/code], or [code]a < b[/code] respectively. </description> <tutorials> </tutorials> diff --git a/doc/classes/VisualShaderNodeIs.xml b/doc/classes/VisualShaderNodeIs.xml index 35832f448f..fa5c83771e 100644 --- a/doc/classes/VisualShaderNodeIs.xml +++ b/doc/classes/VisualShaderNodeIs.xml @@ -18,7 +18,7 @@ Comparison with [code]INF[/code] (Infinity). </constant> <constant name="FUNC_IS_NAN" value="1" enum="Function"> - Comparison with [code]NaN[/code] (Not a Number; denotes invalid numeric results, e.g. division by zero). + Comparison with [code]NaN[/code] (Not a Number; indicates invalid numeric results, such as division by zero). </constant> <constant name="FUNC_MAX" value="2" enum="Function"> Represents the size of the [enum Function] enum. diff --git a/doc/classes/VisualShaderNodeTexture.xml b/doc/classes/VisualShaderNodeTexture.xml index 5b38683eba..eda09573ad 100644 --- a/doc/classes/VisualShaderNodeTexture.xml +++ b/doc/classes/VisualShaderNodeTexture.xml @@ -51,7 +51,7 @@ No hints are added to the uniform declaration. </constant> <constant name="TYPE_COLOR" value="1" enum="TextureType"> - Adds [code]hint_albedo[/code] as hint to the uniform declaration for proper sRGB to linear conversion. + Adds [code]source_color[/code] as hint to the uniform declaration for proper sRGB to linear conversion. </constant> <constant name="TYPE_NORMAL_MAP" value="2" enum="TextureType"> Adds [code]hint_normal[/code] as hint to the uniform declaration, which internally converts the texture for proper usage as normal map. diff --git a/doc/classes/VisualShaderNodeTextureParameter.xml b/doc/classes/VisualShaderNodeTextureParameter.xml index 79a0657156..aa64016746 100644 --- a/doc/classes/VisualShaderNodeTextureParameter.xml +++ b/doc/classes/VisualShaderNodeTextureParameter.xml @@ -57,24 +57,26 @@ Sample the texture using the filter determined by the node this shader is attached to. </constant> <constant name="FILTER_NEAREST" value="1" enum="TextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="FILTER_LINEAR" value="2" enum="TextureFilter"> - The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="FILTER_NEAREST_MIPMAP" value="3" enum="TextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. This is the fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="FILTER_LINEAR_MIPMAP" value="4" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="FILTER_NEAREST_MIPMAP_ANISOTROPIC" value="5" enum="TextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_LINEAR_MIPMAP] is usually more appropriate. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_NEAREST_MIPMAP] is usually more appropriate in this case. </constant> <constant name="FILTER_LINEAR_MIPMAP_ANISOTROPIC" value="6" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_LINEAR_MIPMAP] is usually more appropriate. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_LINEAR_MIPMAP] is usually more appropriate in this case. </constant> <constant name="FILTER_MAX" value="7" enum="TextureFilter"> Represents the size of the [enum TextureFilter] enum. diff --git a/doc/classes/VisualShaderNodeTransformCompose.xml b/doc/classes/VisualShaderNodeTransformCompose.xml index f2250544a4..6418d2a729 100644 --- a/doc/classes/VisualShaderNodeTransformCompose.xml +++ b/doc/classes/VisualShaderNodeTransformCompose.xml @@ -4,7 +4,7 @@ Composes a [Transform3D] from four [Vector3]s within the visual shader graph. </brief_description> <description> - Creates a 4x4 transform matrix using four vectors of type [code]vec3[/code]. Each vector is one row in the matrix and the last column is a [code]vec4(0, 0, 0, 1)[/code]. + Creates a 4×4 transform matrix using four vectors of type [code]vec3[/code]. Each vector is one row in the matrix and the last column is a [code]vec4(0, 0, 0, 1)[/code]. </description> <tutorials> </tutorials> diff --git a/doc/classes/VisualShaderNodeTransformDecompose.xml b/doc/classes/VisualShaderNodeTransformDecompose.xml index fc4e3151da..0d1403ea1d 100644 --- a/doc/classes/VisualShaderNodeTransformDecompose.xml +++ b/doc/classes/VisualShaderNodeTransformDecompose.xml @@ -4,7 +4,7 @@ Decomposes a [Transform3D] into four [Vector3]s within the visual shader graph. </brief_description> <description> - Takes a 4x4 transform matrix and decomposes it into four [code]vec3[/code] values, one from each row of the matrix. + Takes a 4×4 transform matrix and decomposes it into four [code]vec3[/code] values, one from each row of the matrix. </description> <tutorials> </tutorials> diff --git a/doc/classes/VisualShaderNodeTransformOp.xml b/doc/classes/VisualShaderNodeTransformOp.xml index a6ada4b07e..0993fd52e6 100644 --- a/doc/classes/VisualShaderNodeTransformOp.xml +++ b/doc/classes/VisualShaderNodeTransformOp.xml @@ -4,7 +4,7 @@ A [Transform3D] operator to be used within the visual shader graph. </brief_description> <description> - Applies [member operator] to two transform (4x4 matrices) inputs. + Applies [member operator] to two transform (4×4 matrices) inputs. </description> <tutorials> </tutorials> diff --git a/doc/classes/VisualShaderNodeTransformVecMult.xml b/doc/classes/VisualShaderNodeTransformVecMult.xml index 100bc6645e..27953d4c19 100644 --- a/doc/classes/VisualShaderNodeTransformVecMult.xml +++ b/doc/classes/VisualShaderNodeTransformVecMult.xml @@ -4,7 +4,7 @@ Multiplies a [Transform3D] and a [Vector3] within the visual shader graph. </brief_description> <description> - A multiplication operation on a transform (4x4 matrix) and a vector, with support for different multiplication operators. + A multiplication operation on a transform (4×4 matrix) and a vector, with support for different multiplication operators. </description> <tutorials> </tutorials> diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index 5f6b1960b7..9c0e8011dc 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -97,7 +97,7 @@ <method name="get_contents_minimum_size" qualifiers="const"> <return type="Vector2" /> <description> - Returns the combined minimum size from the child [Control] nodes of the window. Use [method child_controls_changed] to update it when children nodes have changed. + Returns the combined minimum size from the child [Control] nodes of the window. Use [method child_controls_changed] to update it when child nodes have changed. The value returned by this method can be overridden with [method _get_contents_minimum_size]. </description> </method> @@ -129,7 +129,7 @@ <method name="get_theme_color" qualifiers="const"> <return type="Color" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a [Color] from the first matching [Theme] in the tree if that [Theme] has a color item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for more details. @@ -138,7 +138,7 @@ <method name="get_theme_constant" qualifiers="const"> <return type="int" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a constant from the first matching [Theme] in the tree if that [Theme] has a constant item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for more details. @@ -168,7 +168,7 @@ <method name="get_theme_font" qualifiers="const"> <return type="Font" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a [Font] from the first matching [Theme] in the tree if that [Theme] has a font item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -177,7 +177,7 @@ <method name="get_theme_font_size" qualifiers="const"> <return type="int" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a font size from the first matching [Theme] in the tree if that [Theme] has a font size item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -186,7 +186,7 @@ <method name="get_theme_icon" qualifiers="const"> <return type="Texture2D" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns an icon from the first matching [Theme] in the tree if that [Theme] has an icon item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -195,7 +195,7 @@ <method name="get_theme_stylebox" qualifiers="const"> <return type="StyleBox" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns a [StyleBox] from the first matching [Theme] in the tree if that [Theme] has a stylebox item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -222,7 +222,7 @@ <method name="has_theme_color" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a color item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -239,7 +239,7 @@ <method name="has_theme_constant" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a constant item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -256,7 +256,7 @@ <method name="has_theme_font" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -273,7 +273,7 @@ <method name="has_theme_font_size" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font size item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -290,7 +290,7 @@ <method name="has_theme_icon" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has an icon item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -307,7 +307,7 @@ <method name="has_theme_stylebox" qualifiers="const"> <return type="bool" /> <param index="0" name="name" type="StringName" /> - <param index="1" name="theme_type" type="StringName" default="""" /> + <param index="1" name="theme_type" type="StringName" default="&""" /> <description> Returns [code]true[/code] if there is a matching [Theme] in the tree that has a stylebox item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for details. @@ -357,10 +357,10 @@ Centers a native window on the current screen and an embedded window on its embedder [Viewport]. </description> </method> - <method name="move_to_foreground"> + <method name="move_to_foreground" deprecated="Use [method Window.grab_focus] instead."> <return type="void" /> <description> - Moves the [Window] on top of other windows and focuses it. + Causes the window to grab focus, allowing it to receive user input. </description> </method> <method name="popup"> @@ -557,7 +557,7 @@ <member name="always_on_top" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], the window will be on top of all other windows. Does not work if [member transient] is enabled. </member> - <member name="auto_translate" type="bool" setter="set_auto_translate" getter="is_auto_translating" default="true"> + <member name="auto_translate" type="bool" setter="set_auto_translate" getter="is_auto_translating" default="true" deprecated="Use [member Node.auto_translate_mode] instead."> Toggles if any text should automatically change to its translated version depending on the current locale. </member> <member name="borderless" type="bool" setter="set_flag" getter="get_flag" default="false"> @@ -590,6 +590,9 @@ [b]Note:[/b] This property is implemented only on macOS. [b]Note:[/b] This property only works with native windows. </member> + <member name="force_native" type="bool" setter="set_force_native" getter="get_force_native" default="false"> + If [code]true[/code], native window will be used regardless of parent viewport and project settings. + </member> <member name="initial_position" type="int" setter="set_initial_position" getter="get_initial_position" enum="Window.WindowInitialPosition" default="0"> Specifies the initial type of position for the [Window]. See [enum WindowInitialPosition] constants. </member> @@ -668,10 +671,13 @@ If [code]true[/code], the [Window] is transient, i.e. it's considered a child of another [Window]. The transient window will be destroyed with its transient parent and will return focus to their parent when closed. The transient window is displayed on top of a non-exclusive full-screen parent window. Transient windows can't enter full-screen mode. Note that behavior might be different depending on the platform. </member> + <member name="transient_to_focused" type="bool" setter="set_transient_to_focused" getter="is_transient_to_focused" default="false"> + If [code]true[/code], and the [Window] is [member transient], this window will (at the time of becoming visible) become transient to the currently focused window instead of the immediate parent window in the hierarchy. Note that the transient parent is assigned at the time this window becomes visible, so changing it afterwards has no effect until re-shown. + </member> <member name="transparent" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], the [Window]'s background can be transparent. This is best used with embedded windows. [b]Note:[/b] Transparency support is implemented on Linux, macOS and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities. - [b]Note:[/b] This property has no effect if either [member ProjectSettings.display/window/per_pixel_transparency/allowed], or the window's [member Viewport.transparent_bg] is set to [code]false[/code]. + [b]Note:[/b] This property has no effect if [member ProjectSettings.display/window/per_pixel_transparency/allowed] is set to [code]false[/code]. </member> <member name="unfocusable" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], the [Window] can't be focused nor interacted with. It can still be visible. @@ -899,7 +905,7 @@ <theme_item name="title_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)"> The color of the title's text. </theme_item> - <theme_item name="title_outline_modulate" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="title_outline_modulate" data_type="color" type="Color" default="Color(0, 0, 0, 1)"> The color of the title's text outline. </theme_item> <theme_item name="close_h_offset" data_type="constant" type="int" default="18"> diff --git a/doc/classes/WorkerThreadPool.xml b/doc/classes/WorkerThreadPool.xml index d6751d31ce..fa1f08b149 100644 --- a/doc/classes/WorkerThreadPool.xml +++ b/doc/classes/WorkerThreadPool.xml @@ -106,7 +106,7 @@ Pauses the thread that calls this method until the task with the given ID is completed. Returns [constant @GlobalScope.OK] if the task could be successfully awaited. Returns [constant @GlobalScope.ERR_INVALID_PARAMETER] if a task with the passed ID does not exist (maybe because it was already awaited and disposed of). - Returns [constant @GlobalScope.ERR_BUSY] if the call is made from another running task and, due to task scheduling, the task to await is at a lower level in the call stack and therefore can't progress. This is an advanced situation that should only matter when some tasks depend on others. + Returns [constant @GlobalScope.ERR_BUSY] if the call is made from another running task and, due to task scheduling, there's potential for deadlocking (e.g., the task to await may be at a lower level in the call stack and therefore can't progress). This is an advanced situation that should only matter when some tasks depend on others (in the current implementation, the tricky case is a task trying to wait on an older one). </description> </method> </methods> diff --git a/doc/classes/WorldEnvironment.xml b/doc/classes/WorldEnvironment.xml index bceb91ab68..c7ee160174 100644 --- a/doc/classes/WorldEnvironment.xml +++ b/doc/classes/WorldEnvironment.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="WorldEnvironment" inherits="Node" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="WorldEnvironment" inherits="Node" keywords="background, sky" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Default environment properties for the entire scene (post-processing effects, lighting and background settings). </brief_description> @@ -18,6 +18,9 @@ <member name="camera_attributes" type="CameraAttributes" setter="set_camera_attributes" getter="get_camera_attributes"> The default [CameraAttributes] resource to use if none set on the [Camera3D]. </member> + <member name="compositor" type="Compositor" setter="set_compositor" getter="get_compositor"> + The default [Compositor] resource to use if none set on the [Camera3D]. + </member> <member name="environment" type="Environment" setter="set_environment" getter="get_environment"> The [Environment] resource used by this [WorldEnvironment], defining the default properties. </member> diff --git a/doc/classes/XMLParser.xml b/doc/classes/XMLParser.xml index 36795852e0..2b67ff6fbb 100644 --- a/doc/classes/XMLParser.xml +++ b/doc/classes/XMLParser.xml @@ -6,7 +6,7 @@ <description> Provides a low-level interface for creating parsers for [url=https://en.wikipedia.org/wiki/XML]XML[/url] files. This class can serve as base to make custom XML parsers. To parse XML, you must open a file with the [method open] method or a buffer with the [method open_buffer] method. Then, the [method read] method must be called to parse the next nodes. Most of the methods take into consideration the currently parsed node. - Here is an example of using [XMLParser] to parse a SVG file (which is based on XML), printing each element and its attributes as a dictionary: + Here is an example of using [XMLParser] to parse an SVG file (which is based on XML), printing each element and its attributes as a dictionary: [codeblocks] [gdscript] var parser = XMLParser.new() @@ -91,7 +91,8 @@ <method name="get_node_name" qualifiers="const"> <return type="String" /> <description> - Returns the name of an element node. This method will raise an error if the currently parsed node is not of [constant NODE_ELEMENT] or [constant NODE_ELEMENT_END] type. + Returns the name of a node. This method will raise an error if the currently parsed node is a text node. + [b]Note:[/b] The content of a [constant NODE_CDATA] node and the comment string of a [constant NODE_COMMENT] node are also considered names. </description> </method> <method name="get_node_offset" qualifiers="const"> diff --git a/doc/classes/XRAnchor3D.xml b/doc/classes/XRAnchor3D.xml index 9390d5c545..cdfe1da90e 100644 --- a/doc/classes/XRAnchor3D.xml +++ b/doc/classes/XRAnchor3D.xml @@ -4,7 +4,7 @@ An anchor point in AR space. </brief_description> <description> - The [XRAnchor3D] point is a spatial node that maps a real world location identified by the AR platform to a position within the game world. For example, as long as plane detection in ARKit is on, ARKit will identify and update the position of planes (tables, floors, etc) and create anchors for them. + The [XRAnchor3D] point is an [XRNode3D] that maps a real world location identified by the AR platform to a position within the game world. For example, as long as plane detection in ARKit is on, ARKit will identify and update the position of planes (tables, floors, etc.) and create anchors for them. This node is mapped to one of the anchors through its unique ID. When you receive a signal that a new anchor is available, you should add this node to your scene for that anchor. You can predefine nodes and set the ID; the nodes will simply remain on 0,0,0 until a plane is recognized. Keep in mind that, as long as plane detection is enabled, the size, placing and orientation of an anchor will be updated as the detection logic learns more about the real world out there especially if only part of the surface is in view. </description> diff --git a/doc/classes/XRBodyModifier3D.xml b/doc/classes/XRBodyModifier3D.xml new file mode 100644 index 0000000000..49a226c106 --- /dev/null +++ b/doc/classes/XRBodyModifier3D.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="XRBodyModifier3D" inherits="SkeletonModifier3D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A node for driving body meshes from [XRBodyTracker] data. + </brief_description> + <description> + This node uses body tracking data from a [XRBodyTracker] to animate the skeleton of a body mesh. + This node positions itself at the [constant XRBodyTracker.JOINT_ROOT] position and scales itself to [member XRServer.world_scale]. Adding the body model as a child of this node will result in the model being positioned and scaled correctly for XR experiences. + The body tracking position-data is scaled by [member Skeleton3D.motion_scale] when applied to the skeleton, which can be used to adjust the tracked body to match the scale of the body model. + </description> + <tutorials> + <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> + </tutorials> + <members> + <member name="body_tracker" type="StringName" setter="set_body_tracker" getter="get_body_tracker" default="&"/user/body""> + The name of the [XRBodyTracker] registered with [XRServer] to obtain the body tracking data from. + </member> + <member name="body_update" type="int" setter="set_body_update" getter="get_body_update" enum="XRBodyModifier3D.BodyUpdate" is_bitfield="true" default="7"> + Specifies the body parts to update. + </member> + <member name="bone_update" type="int" setter="set_bone_update" getter="get_bone_update" enum="XRBodyModifier3D.BoneUpdate" default="0"> + Specifies the type of updates to perform on the bones. + </member> + <member name="show_when_tracked" type="bool" setter="set_show_when_tracked" getter="get_show_when_tracked" default="true"> + If true then the nodes visibility is determined by whether tracking data is available. + </member> + </members> + <constants> + <constant name="BODY_UPDATE_UPPER_BODY" value="1" enum="BodyUpdate" is_bitfield="true"> + The skeleton's upper body joints are updated. + </constant> + <constant name="BODY_UPDATE_LOWER_BODY" value="2" enum="BodyUpdate" is_bitfield="true"> + The skeleton's lower body joints are updated. + </constant> + <constant name="BODY_UPDATE_HANDS" value="4" enum="BodyUpdate" is_bitfield="true"> + The skeleton's hand joints are updated. + </constant> + <constant name="BONE_UPDATE_FULL" value="0" enum="BoneUpdate"> + The skeleton's bones are fully updated (both position and rotation) to match the tracked bones. + </constant> + <constant name="BONE_UPDATE_ROTATION_ONLY" value="1" enum="BoneUpdate"> + The skeleton's bones are only rotated to align with the tracked bones, preserving bone length. + </constant> + <constant name="BONE_UPDATE_MAX" value="2" enum="BoneUpdate"> + Represents the size of the [enum BoneUpdate] enum. + </constant> + </constants> +</class> diff --git a/doc/classes/XRBodyTracker.xml b/doc/classes/XRBodyTracker.xml new file mode 100644 index 0000000000..9c869b4f5f --- /dev/null +++ b/doc/classes/XRBodyTracker.xml @@ -0,0 +1,307 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="XRBodyTracker" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A tracked body in XR. + </brief_description> + <description> + A body tracking system will create an instance of this object and add it to the [XRServer]. This tracking system will then obtain skeleton data, convert it to the Godot Humanoid skeleton and store this data on the [XRBodyTracker] object. + Use [XRBodyModifier3D] to animate a body mesh using body tracking data. + </description> + <tutorials> + <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> + </tutorials> + <methods> + <method name="get_joint_flags" qualifiers="const"> + <return type="int" enum="XRBodyTracker.JointFlags" is_bitfield="true" /> + <param index="0" name="joint" type="int" enum="XRBodyTracker.Joint" /> + <description> + Returns flags about the validity of the tracking data for the given body joint (see [enum XRBodyTracker.JointFlags]). + </description> + </method> + <method name="get_joint_transform" qualifiers="const"> + <return type="Transform3D" /> + <param index="0" name="joint" type="int" enum="XRBodyTracker.Joint" /> + <description> + Returns the transform for the given body joint. + </description> + </method> + <method name="set_joint_flags"> + <return type="void" /> + <param index="0" name="joint" type="int" enum="XRBodyTracker.Joint" /> + <param index="1" name="flags" type="int" enum="XRBodyTracker.JointFlags" is_bitfield="true" /> + <description> + Sets flags about the validity of the tracking data for the given body joint. + </description> + </method> + <method name="set_joint_transform"> + <return type="void" /> + <param index="0" name="joint" type="int" enum="XRBodyTracker.Joint" /> + <param index="1" name="transform" type="Transform3D" /> + <description> + Sets the transform for the given body joint. + </description> + </method> + </methods> + <members> + <member name="body_flags" type="int" setter="set_body_flags" getter="get_body_flags" enum="XRBodyTracker.BodyFlags" is_bitfield="true" default="0"> + The type of body tracking data captured. + </member> + <member name="has_tracking_data" type="bool" setter="set_has_tracking_data" getter="get_has_tracking_data" default="false"> + If [code]true[/code], the body tracking data is valid. + </member> + </members> + <constants> + <constant name="BODY_FLAG_UPPER_BODY_SUPPORTED" value="1" enum="BodyFlags" is_bitfield="true"> + Upper body tracking supported. + </constant> + <constant name="BODY_FLAG_LOWER_BODY_SUPPORTED" value="2" enum="BodyFlags" is_bitfield="true"> + Lower body tracking supported. + </constant> + <constant name="BODY_FLAG_HANDS_SUPPORTED" value="4" enum="BodyFlags" is_bitfield="true"> + Hand tracking supported. + </constant> + <constant name="JOINT_ROOT" value="0" enum="Joint"> + Root joint. + </constant> + <constant name="JOINT_HIPS" value="1" enum="Joint"> + Hips joint. + </constant> + <constant name="JOINT_SPINE" value="2" enum="Joint"> + Spine joint. + </constant> + <constant name="JOINT_CHEST" value="3" enum="Joint"> + Chest joint. + </constant> + <constant name="JOINT_UPPER_CHEST" value="4" enum="Joint"> + Upper chest joint. + </constant> + <constant name="JOINT_NECK" value="5" enum="Joint"> + Neck joint. + </constant> + <constant name="JOINT_HEAD" value="6" enum="Joint"> + Head joint. + </constant> + <constant name="JOINT_HEAD_TIP" value="7" enum="Joint"> + Head tip joint. + </constant> + <constant name="JOINT_LEFT_SHOULDER" value="8" enum="Joint"> + Left shoulder joint. + </constant> + <constant name="JOINT_LEFT_UPPER_ARM" value="9" enum="Joint"> + Left upper arm joint. + </constant> + <constant name="JOINT_LEFT_LOWER_ARM" value="10" enum="Joint"> + Left lower arm joint. + </constant> + <constant name="JOINT_RIGHT_SHOULDER" value="11" enum="Joint"> + Right shoulder joint. + </constant> + <constant name="JOINT_RIGHT_UPPER_ARM" value="12" enum="Joint"> + Right upper arm joint. + </constant> + <constant name="JOINT_RIGHT_LOWER_ARM" value="13" enum="Joint"> + Right lower arm joint. + </constant> + <constant name="JOINT_LEFT_UPPER_LEG" value="14" enum="Joint"> + Left upper leg joint. + </constant> + <constant name="JOINT_LEFT_LOWER_LEG" value="15" enum="Joint"> + Left lower leg joint. + </constant> + <constant name="JOINT_LEFT_FOOT" value="16" enum="Joint"> + Left foot joint. + </constant> + <constant name="JOINT_LEFT_TOES" value="17" enum="Joint"> + Left toes joint. + </constant> + <constant name="JOINT_RIGHT_UPPER_LEG" value="18" enum="Joint"> + Right upper leg joint. + </constant> + <constant name="JOINT_RIGHT_LOWER_LEG" value="19" enum="Joint"> + Right lower leg joint. + </constant> + <constant name="JOINT_RIGHT_FOOT" value="20" enum="Joint"> + Right foot joint. + </constant> + <constant name="JOINT_RIGHT_TOES" value="21" enum="Joint"> + Right toes joint. + </constant> + <constant name="JOINT_LEFT_HAND" value="22" enum="Joint"> + Left hand joint. + </constant> + <constant name="JOINT_LEFT_PALM" value="23" enum="Joint"> + Left palm joint. + </constant> + <constant name="JOINT_LEFT_WRIST" value="24" enum="Joint"> + Left wrist joint. + </constant> + <constant name="JOINT_LEFT_THUMB_METACARPAL" value="25" enum="Joint"> + Left thumb metacarpal joint. + </constant> + <constant name="JOINT_LEFT_THUMB_PHALANX_PROXIMAL" value="26" enum="Joint"> + Left thumb phalanx proximal joint. + </constant> + <constant name="JOINT_LEFT_THUMB_PHALANX_DISTAL" value="27" enum="Joint"> + Left thumb phalanx distal joint. + </constant> + <constant name="JOINT_LEFT_THUMB_TIP" value="28" enum="Joint"> + Left thumb tip joint. + </constant> + <constant name="JOINT_LEFT_INDEX_FINGER_METACARPAL" value="29" enum="Joint"> + Left index finger metacarpal joint. + </constant> + <constant name="JOINT_LEFT_INDEX_FINGER_PHALANX_PROXIMAL" value="30" enum="Joint"> + Left index finger phalanx proximal joint. + </constant> + <constant name="JOINT_LEFT_INDEX_FINGER_PHALANX_INTERMEDIATE" value="31" enum="Joint"> + Left index finger phalanx intermediate joint. + </constant> + <constant name="JOINT_LEFT_INDEX_FINGER_PHALANX_DISTAL" value="32" enum="Joint"> + Left index finger phalanx distal joint. + </constant> + <constant name="JOINT_LEFT_INDEX_FINGER_TIP" value="33" enum="Joint"> + Left index finger tip joint. + </constant> + <constant name="JOINT_LEFT_MIDDLE_FINGER_METACARPAL" value="34" enum="Joint"> + Left middle finger metacarpal joint. + </constant> + <constant name="JOINT_LEFT_MIDDLE_FINGER_PHALANX_PROXIMAL" value="35" enum="Joint"> + Left middle finger phalanx proximal joint. + </constant> + <constant name="JOINT_LEFT_MIDDLE_FINGER_PHALANX_INTERMEDIATE" value="36" enum="Joint"> + Left middle finger phalanx intermediate joint. + </constant> + <constant name="JOINT_LEFT_MIDDLE_FINGER_PHALANX_DISTAL" value="37" enum="Joint"> + Left middle finger phalanx distal joint. + </constant> + <constant name="JOINT_LEFT_MIDDLE_FINGER_TIP" value="38" enum="Joint"> + Left middle finger tip joint. + </constant> + <constant name="JOINT_LEFT_RING_FINGER_METACARPAL" value="39" enum="Joint"> + Left ring finger metacarpal joint. + </constant> + <constant name="JOINT_LEFT_RING_FINGER_PHALANX_PROXIMAL" value="40" enum="Joint"> + Left ring finger phalanx proximal joint. + </constant> + <constant name="JOINT_LEFT_RING_FINGER_PHALANX_INTERMEDIATE" value="41" enum="Joint"> + Left ring finger phalanx intermediate joint. + </constant> + <constant name="JOINT_LEFT_RING_FINGER_PHALANX_DISTAL" value="42" enum="Joint"> + Left ring finger phalanx distal joint. + </constant> + <constant name="JOINT_LEFT_RING_FINGER_TIP" value="43" enum="Joint"> + Left ring finger tip joint. + </constant> + <constant name="JOINT_LEFT_PINKY_FINGER_METACARPAL" value="44" enum="Joint"> + Left pinky finger metacarpal joint. + </constant> + <constant name="JOINT_LEFT_PINKY_FINGER_PHALANX_PROXIMAL" value="45" enum="Joint"> + Left pinky finger phalanx proximal joint. + </constant> + <constant name="JOINT_LEFT_PINKY_FINGER_PHALANX_INTERMEDIATE" value="46" enum="Joint"> + Left pinky finger phalanx intermediate joint. + </constant> + <constant name="JOINT_LEFT_PINKY_FINGER_PHALANX_DISTAL" value="47" enum="Joint"> + Left pinky finger phalanx distal joint. + </constant> + <constant name="JOINT_LEFT_PINKY_FINGER_TIP" value="48" enum="Joint"> + Left pinky finger tip joint. + </constant> + <constant name="JOINT_RIGHT_HAND" value="49" enum="Joint"> + Right hand joint. + </constant> + <constant name="JOINT_RIGHT_PALM" value="50" enum="Joint"> + Right palm joint. + </constant> + <constant name="JOINT_RIGHT_WRIST" value="51" enum="Joint"> + Right wrist joint. + </constant> + <constant name="JOINT_RIGHT_THUMB_METACARPAL" value="52" enum="Joint"> + Right thumb metacarpal joint. + </constant> + <constant name="JOINT_RIGHT_THUMB_PHALANX_PROXIMAL" value="53" enum="Joint"> + Right thumb phalanx proximal joint. + </constant> + <constant name="JOINT_RIGHT_THUMB_PHALANX_DISTAL" value="54" enum="Joint"> + Right thumb phalanx distal joint. + </constant> + <constant name="JOINT_RIGHT_THUMB_TIP" value="55" enum="Joint"> + Right thumb tip joint. + </constant> + <constant name="JOINT_RIGHT_INDEX_FINGER_METACARPAL" value="56" enum="Joint"> + Right index finger metacarpal joint. + </constant> + <constant name="JOINT_RIGHT_INDEX_FINGER_PHALANX_PROXIMAL" value="57" enum="Joint"> + Right index finger phalanx proximal joint. + </constant> + <constant name="JOINT_RIGHT_INDEX_FINGER_PHALANX_INTERMEDIATE" value="58" enum="Joint"> + Right index finger phalanx intermediate joint. + </constant> + <constant name="JOINT_RIGHT_INDEX_FINGER_PHALANX_DISTAL" value="59" enum="Joint"> + Right index finger phalanx distal joint. + </constant> + <constant name="JOINT_RIGHT_INDEX_FINGER_TIP" value="60" enum="Joint"> + Right index finger tip joint. + </constant> + <constant name="JOINT_RIGHT_MIDDLE_FINGER_METACARPAL" value="61" enum="Joint"> + Right middle finger metacarpal joint. + </constant> + <constant name="JOINT_RIGHT_MIDDLE_FINGER_PHALANX_PROXIMAL" value="62" enum="Joint"> + Right middle finger phalanx proximal joint. + </constant> + <constant name="JOINT_RIGHT_MIDDLE_FINGER_PHALANX_INTERMEDIATE" value="63" enum="Joint"> + Right middle finger phalanx intermediate joint. + </constant> + <constant name="JOINT_RIGHT_MIDDLE_FINGER_PHALANX_DISTAL" value="64" enum="Joint"> + Right middle finger phalanx distal joint. + </constant> + <constant name="JOINT_RIGHT_MIDDLE_FINGER_TIP" value="65" enum="Joint"> + Right middle finger tip joint. + </constant> + <constant name="JOINT_RIGHT_RING_FINGER_METACARPAL" value="66" enum="Joint"> + Right ring finger metacarpal joint. + </constant> + <constant name="JOINT_RIGHT_RING_FINGER_PHALANX_PROXIMAL" value="67" enum="Joint"> + Right ring finger phalanx proximal joint. + </constant> + <constant name="JOINT_RIGHT_RING_FINGER_PHALANX_INTERMEDIATE" value="68" enum="Joint"> + Right ring finger phalanx intermediate joint. + </constant> + <constant name="JOINT_RIGHT_RING_FINGER_PHALANX_DISTAL" value="69" enum="Joint"> + Right ring finger phalanx distal joint. + </constant> + <constant name="JOINT_RIGHT_RING_FINGER_TIP" value="70" enum="Joint"> + Right ring finger tip joint. + </constant> + <constant name="JOINT_RIGHT_PINKY_FINGER_METACARPAL" value="71" enum="Joint"> + Right pinky finger metacarpal joint. + </constant> + <constant name="JOINT_RIGHT_PINKY_FINGER_PHALANX_PROXIMAL" value="72" enum="Joint"> + Right pinky finger phalanx proximal joint. + </constant> + <constant name="JOINT_RIGHT_PINKY_FINGER_PHALANX_INTERMEDIATE" value="73" enum="Joint"> + Right pinky finger phalanx intermediate joint. + </constant> + <constant name="JOINT_RIGHT_PINKY_FINGER_PHALANX_DISTAL" value="74" enum="Joint"> + Right pinky finger phalanx distal joint. + </constant> + <constant name="JOINT_RIGHT_PINKY_FINGER_TIP" value="75" enum="Joint"> + Right pinky finger tip joint. + </constant> + <constant name="JOINT_MAX" value="76" enum="Joint"> + Represents the size of the [enum Joint] enum. + </constant> + <constant name="JOINT_FLAG_ORIENTATION_VALID" value="1" enum="JointFlags" is_bitfield="true"> + The joint's orientation data is valid. + </constant> + <constant name="JOINT_FLAG_ORIENTATION_TRACKED" value="2" enum="JointFlags" is_bitfield="true"> + The joint's orientation is actively tracked. May not be set if tracking has been temporarily lost. + </constant> + <constant name="JOINT_FLAG_POSITION_VALID" value="4" enum="JointFlags" is_bitfield="true"> + The joint's position data is valid. + </constant> + <constant name="JOINT_FLAG_POSITION_TRACKED" value="8" enum="JointFlags" is_bitfield="true"> + The joint's position is actively tracked. May not be set if tracking has been temporarily lost. + </constant> + </constants> +</class> diff --git a/doc/classes/XRController3D.xml b/doc/classes/XRController3D.xml index ee67477eb0..8a068661c9 100644 --- a/doc/classes/XRController3D.xml +++ b/doc/classes/XRController3D.xml @@ -75,5 +75,11 @@ Emitted when a thumbstick or thumbpad on this controller is moved. </description> </signal> + <signal name="profile_changed"> + <param index="0" name="role" type="String" /> + <description> + Emitted when the interaction profile on this controller is changed. + </description> + </signal> </signals> </class> diff --git a/doc/classes/XRFaceModifier3D.xml b/doc/classes/XRFaceModifier3D.xml new file mode 100644 index 0000000000..8caa74cff7 --- /dev/null +++ b/doc/classes/XRFaceModifier3D.xml @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="XRFaceModifier3D" inherits="Node3D" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A node for driving standard face meshes from [XRFaceTracker] weights. + </brief_description> + <description> + This node applies weights from a [XRFaceTracker] to a mesh with supporting face blend shapes. + The [url=https://docs.vrcft.io/docs/tutorial-avatars/tutorial-avatars-extras/unified-blendshapes]Unified Expressions[/url] blend shapes are supported, as well as ARKit and SRanipal blend shapes. + The node attempts to identify blend shapes based on name matching. Blend shapes should match the names listed in the [url=https://docs.vrcft.io/docs/tutorial-avatars/tutorial-avatars-extras/compatibility/overview]Unified Expressions Compatibility[/url] chart. + </description> + <tutorials> + <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> + </tutorials> + <members> + <member name="face_tracker" type="StringName" setter="set_face_tracker" getter="get_face_tracker" default="&"/user/head""> + The [XRFaceTracker] path. + </member> + <member name="target" type="NodePath" setter="set_target" getter="get_target" default="NodePath("")"> + The [NodePath] of the face [MeshInstance3D]. + </member> + </members> +</class> diff --git a/doc/classes/XRFaceTracker.xml b/doc/classes/XRFaceTracker.xml new file mode 100644 index 0000000000..96ed137324 --- /dev/null +++ b/doc/classes/XRFaceTracker.xml @@ -0,0 +1,469 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="XRFaceTracker" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A tracked face. + </brief_description> + <description> + An instance of this object represents a tracked face and its corresponding blend shapes. The blend shapes come from the [url=https://docs.vrcft.io/docs/tutorial-avatars/tutorial-avatars-extras/unified-blendshapes]Unified Expressions[/url] standard, and contain extended details and visuals for each blend shape. Additionally the [url=https://docs.vrcft.io/docs/tutorial-avatars/tutorial-avatars-extras/compatibility/overview]Tracking Standard Comparison[/url] page documents the relationship between Unified Expressions and other standards. + As face trackers are turned on they are registered with the [XRServer]. + </description> + <tutorials> + <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> + </tutorials> + <methods> + <method name="get_blend_shape" qualifiers="const"> + <return type="float" /> + <param index="0" name="blend_shape" type="int" enum="XRFaceTracker.BlendShapeEntry" /> + <description> + Returns the requested face blend shape weight. + </description> + </method> + <method name="set_blend_shape"> + <return type="void" /> + <param index="0" name="blend_shape" type="int" enum="XRFaceTracker.BlendShapeEntry" /> + <param index="1" name="weight" type="float" /> + <description> + Sets a face blend shape weight. + </description> + </method> + </methods> + <members> + <member name="blend_shapes" type="PackedFloat32Array" setter="set_blend_shapes" getter="get_blend_shapes" default="PackedFloat32Array()"> + The array of face blend shape weights with indices corresponding to the [enum BlendShapeEntry] enum. + </member> + </members> + <constants> + <constant name="FT_EYE_LOOK_OUT_RIGHT" value="0" enum="BlendShapeEntry"> + Right eye looks outwards. + </constant> + <constant name="FT_EYE_LOOK_IN_RIGHT" value="1" enum="BlendShapeEntry"> + Right eye looks inwards. + </constant> + <constant name="FT_EYE_LOOK_UP_RIGHT" value="2" enum="BlendShapeEntry"> + Right eye looks upwards. + </constant> + <constant name="FT_EYE_LOOK_DOWN_RIGHT" value="3" enum="BlendShapeEntry"> + Right eye looks downwards. + </constant> + <constant name="FT_EYE_LOOK_OUT_LEFT" value="4" enum="BlendShapeEntry"> + Left eye looks outwards. + </constant> + <constant name="FT_EYE_LOOK_IN_LEFT" value="5" enum="BlendShapeEntry"> + Left eye looks inwards. + </constant> + <constant name="FT_EYE_LOOK_UP_LEFT" value="6" enum="BlendShapeEntry"> + Left eye looks upwards. + </constant> + <constant name="FT_EYE_LOOK_DOWN_LEFT" value="7" enum="BlendShapeEntry"> + Left eye looks downwards. + </constant> + <constant name="FT_EYE_CLOSED_RIGHT" value="8" enum="BlendShapeEntry"> + Closes the right eyelid. + </constant> + <constant name="FT_EYE_CLOSED_LEFT" value="9" enum="BlendShapeEntry"> + Closes the left eyelid. + </constant> + <constant name="FT_EYE_SQUINT_RIGHT" value="10" enum="BlendShapeEntry"> + Squeezes the right eye socket muscles. + </constant> + <constant name="FT_EYE_SQUINT_LEFT" value="11" enum="BlendShapeEntry"> + Squeezes the left eye socket muscles. + </constant> + <constant name="FT_EYE_WIDE_RIGHT" value="12" enum="BlendShapeEntry"> + Right eyelid widens beyond relaxed. + </constant> + <constant name="FT_EYE_WIDE_LEFT" value="13" enum="BlendShapeEntry"> + Left eyelid widens beyond relaxed. + </constant> + <constant name="FT_EYE_DILATION_RIGHT" value="14" enum="BlendShapeEntry"> + Dilates the right eye pupil. + </constant> + <constant name="FT_EYE_DILATION_LEFT" value="15" enum="BlendShapeEntry"> + Dilates the left eye pupil. + </constant> + <constant name="FT_EYE_CONSTRICT_RIGHT" value="16" enum="BlendShapeEntry"> + Constricts the right eye pupil. + </constant> + <constant name="FT_EYE_CONSTRICT_LEFT" value="17" enum="BlendShapeEntry"> + Constricts the left eye pupil. + </constant> + <constant name="FT_BROW_PINCH_RIGHT" value="18" enum="BlendShapeEntry"> + Right eyebrow pinches in. + </constant> + <constant name="FT_BROW_PINCH_LEFT" value="19" enum="BlendShapeEntry"> + Left eyebrow pinches in. + </constant> + <constant name="FT_BROW_LOWERER_RIGHT" value="20" enum="BlendShapeEntry"> + Outer right eyebrow pulls down. + </constant> + <constant name="FT_BROW_LOWERER_LEFT" value="21" enum="BlendShapeEntry"> + Outer left eyebrow pulls down. + </constant> + <constant name="FT_BROW_INNER_UP_RIGHT" value="22" enum="BlendShapeEntry"> + Inner right eyebrow pulls up. + </constant> + <constant name="FT_BROW_INNER_UP_LEFT" value="23" enum="BlendShapeEntry"> + Inner left eyebrow pulls up. + </constant> + <constant name="FT_BROW_OUTER_UP_RIGHT" value="24" enum="BlendShapeEntry"> + Outer right eyebrow pulls up. + </constant> + <constant name="FT_BROW_OUTER_UP_LEFT" value="25" enum="BlendShapeEntry"> + Outer left eyebrow pulls up. + </constant> + <constant name="FT_NOSE_SNEER_RIGHT" value="26" enum="BlendShapeEntry"> + Right side face sneers. + </constant> + <constant name="FT_NOSE_SNEER_LEFT" value="27" enum="BlendShapeEntry"> + Left side face sneers. + </constant> + <constant name="FT_NASAL_DILATION_RIGHT" value="28" enum="BlendShapeEntry"> + Right side nose canal dilates. + </constant> + <constant name="FT_NASAL_DILATION_LEFT" value="29" enum="BlendShapeEntry"> + Left side nose canal dilates. + </constant> + <constant name="FT_NASAL_CONSTRICT_RIGHT" value="30" enum="BlendShapeEntry"> + Right side nose canal constricts. + </constant> + <constant name="FT_NASAL_CONSTRICT_LEFT" value="31" enum="BlendShapeEntry"> + Left side nose canal constricts. + </constant> + <constant name="FT_CHEEK_SQUINT_RIGHT" value="32" enum="BlendShapeEntry"> + Raises the right side cheek. + </constant> + <constant name="FT_CHEEK_SQUINT_LEFT" value="33" enum="BlendShapeEntry"> + Raises the left side cheek. + </constant> + <constant name="FT_CHEEK_PUFF_RIGHT" value="34" enum="BlendShapeEntry"> + Puffs the right side cheek. + </constant> + <constant name="FT_CHEEK_PUFF_LEFT" value="35" enum="BlendShapeEntry"> + Puffs the left side cheek. + </constant> + <constant name="FT_CHEEK_SUCK_RIGHT" value="36" enum="BlendShapeEntry"> + Sucks in the right side cheek. + </constant> + <constant name="FT_CHEEK_SUCK_LEFT" value="37" enum="BlendShapeEntry"> + Sucks in the left side cheek. + </constant> + <constant name="FT_JAW_OPEN" value="38" enum="BlendShapeEntry"> + Opens jawbone. + </constant> + <constant name="FT_MOUTH_CLOSED" value="39" enum="BlendShapeEntry"> + Closes the mouth. + </constant> + <constant name="FT_JAW_RIGHT" value="40" enum="BlendShapeEntry"> + Pushes jawbone right. + </constant> + <constant name="FT_JAW_LEFT" value="41" enum="BlendShapeEntry"> + Pushes jawbone left. + </constant> + <constant name="FT_JAW_FORWARD" value="42" enum="BlendShapeEntry"> + Pushes jawbone forward. + </constant> + <constant name="FT_JAW_BACKWARD" value="43" enum="BlendShapeEntry"> + Pushes jawbone backward. + </constant> + <constant name="FT_JAW_CLENCH" value="44" enum="BlendShapeEntry"> + Flexes jaw muscles. + </constant> + <constant name="FT_JAW_MANDIBLE_RAISE" value="45" enum="BlendShapeEntry"> + Raises the jawbone. + </constant> + <constant name="FT_LIP_SUCK_UPPER_RIGHT" value="46" enum="BlendShapeEntry"> + Upper right lip part tucks in the mouth. + </constant> + <constant name="FT_LIP_SUCK_UPPER_LEFT" value="47" enum="BlendShapeEntry"> + Upper left lip part tucks in the mouth. + </constant> + <constant name="FT_LIP_SUCK_LOWER_RIGHT" value="48" enum="BlendShapeEntry"> + Lower right lip part tucks in the mouth. + </constant> + <constant name="FT_LIP_SUCK_LOWER_LEFT" value="49" enum="BlendShapeEntry"> + Lower left lip part tucks in the mouth. + </constant> + <constant name="FT_LIP_SUCK_CORNER_RIGHT" value="50" enum="BlendShapeEntry"> + Right lip corner folds into the mouth. + </constant> + <constant name="FT_LIP_SUCK_CORNER_LEFT" value="51" enum="BlendShapeEntry"> + Left lip corner folds into the mouth. + </constant> + <constant name="FT_LIP_FUNNEL_UPPER_RIGHT" value="52" enum="BlendShapeEntry"> + Upper right lip part pushes into a funnel. + </constant> + <constant name="FT_LIP_FUNNEL_UPPER_LEFT" value="53" enum="BlendShapeEntry"> + Upper left lip part pushes into a funnel. + </constant> + <constant name="FT_LIP_FUNNEL_LOWER_RIGHT" value="54" enum="BlendShapeEntry"> + Lower right lip part pushes into a funnel. + </constant> + <constant name="FT_LIP_FUNNEL_LOWER_LEFT" value="55" enum="BlendShapeEntry"> + Lower left lip part pushes into a funnel. + </constant> + <constant name="FT_LIP_PUCKER_UPPER_RIGHT" value="56" enum="BlendShapeEntry"> + Upper right lip part pushes outwards. + </constant> + <constant name="FT_LIP_PUCKER_UPPER_LEFT" value="57" enum="BlendShapeEntry"> + Upper left lip part pushes outwards. + </constant> + <constant name="FT_LIP_PUCKER_LOWER_RIGHT" value="58" enum="BlendShapeEntry"> + Lower right lip part pushes outwards. + </constant> + <constant name="FT_LIP_PUCKER_LOWER_LEFT" value="59" enum="BlendShapeEntry"> + Lower left lip part pushes outwards. + </constant> + <constant name="FT_MOUTH_UPPER_UP_RIGHT" value="60" enum="BlendShapeEntry"> + Upper right part of the lip pulls up. + </constant> + <constant name="FT_MOUTH_UPPER_UP_LEFT" value="61" enum="BlendShapeEntry"> + Upper left part of the lip pulls up. + </constant> + <constant name="FT_MOUTH_LOWER_DOWN_RIGHT" value="62" enum="BlendShapeEntry"> + Lower right part of the lip pulls up. + </constant> + <constant name="FT_MOUTH_LOWER_DOWN_LEFT" value="63" enum="BlendShapeEntry"> + Lower left part of the lip pulls up. + </constant> + <constant name="FT_MOUTH_UPPER_DEEPEN_RIGHT" value="64" enum="BlendShapeEntry"> + Upper right lip part pushes in the cheek. + </constant> + <constant name="FT_MOUTH_UPPER_DEEPEN_LEFT" value="65" enum="BlendShapeEntry"> + Upper left lip part pushes in the cheek. + </constant> + <constant name="FT_MOUTH_UPPER_RIGHT" value="66" enum="BlendShapeEntry"> + Moves upper lip right. + </constant> + <constant name="FT_MOUTH_UPPER_LEFT" value="67" enum="BlendShapeEntry"> + Moves upper lip left. + </constant> + <constant name="FT_MOUTH_LOWER_RIGHT" value="68" enum="BlendShapeEntry"> + Moves lower lip right. + </constant> + <constant name="FT_MOUTH_LOWER_LEFT" value="69" enum="BlendShapeEntry"> + Moves lower lip left. + </constant> + <constant name="FT_MOUTH_CORNER_PULL_RIGHT" value="70" enum="BlendShapeEntry"> + Right lip corner pulls diagonally up and out. + </constant> + <constant name="FT_MOUTH_CORNER_PULL_LEFT" value="71" enum="BlendShapeEntry"> + Left lip corner pulls diagonally up and out. + </constant> + <constant name="FT_MOUTH_CORNER_SLANT_RIGHT" value="72" enum="BlendShapeEntry"> + Right corner lip slants up. + </constant> + <constant name="FT_MOUTH_CORNER_SLANT_LEFT" value="73" enum="BlendShapeEntry"> + Left corner lip slants up. + </constant> + <constant name="FT_MOUTH_FROWN_RIGHT" value="74" enum="BlendShapeEntry"> + Right corner lip pulls down. + </constant> + <constant name="FT_MOUTH_FROWN_LEFT" value="75" enum="BlendShapeEntry"> + Left corner lip pulls down. + </constant> + <constant name="FT_MOUTH_STRETCH_RIGHT" value="76" enum="BlendShapeEntry"> + Mouth corner lip pulls out and down. + </constant> + <constant name="FT_MOUTH_STRETCH_LEFT" value="77" enum="BlendShapeEntry"> + Mouth corner lip pulls out and down. + </constant> + <constant name="FT_MOUTH_DIMPLE_RIGHT" value="78" enum="BlendShapeEntry"> + Right lip corner is pushed backwards. + </constant> + <constant name="FT_MOUTH_DIMPLE_LEFT" value="79" enum="BlendShapeEntry"> + Left lip corner is pushed backwards. + </constant> + <constant name="FT_MOUTH_RAISER_UPPER" value="80" enum="BlendShapeEntry"> + Raises and slightly pushes out the upper mouth. + </constant> + <constant name="FT_MOUTH_RAISER_LOWER" value="81" enum="BlendShapeEntry"> + Raises and slightly pushes out the lower mouth. + </constant> + <constant name="FT_MOUTH_PRESS_RIGHT" value="82" enum="BlendShapeEntry"> + Right side lips press and flatten together vertically. + </constant> + <constant name="FT_MOUTH_PRESS_LEFT" value="83" enum="BlendShapeEntry"> + Left side lips press and flatten together vertically. + </constant> + <constant name="FT_MOUTH_TIGHTENER_RIGHT" value="84" enum="BlendShapeEntry"> + Right side lips squeeze together horizontally. + </constant> + <constant name="FT_MOUTH_TIGHTENER_LEFT" value="85" enum="BlendShapeEntry"> + Left side lips squeeze together horizontally. + </constant> + <constant name="FT_TONGUE_OUT" value="86" enum="BlendShapeEntry"> + Tongue visibly sticks out of the mouth. + </constant> + <constant name="FT_TONGUE_UP" value="87" enum="BlendShapeEntry"> + Tongue points upwards. + </constant> + <constant name="FT_TONGUE_DOWN" value="88" enum="BlendShapeEntry"> + Tongue points downwards. + </constant> + <constant name="FT_TONGUE_RIGHT" value="89" enum="BlendShapeEntry"> + Tongue points right. + </constant> + <constant name="FT_TONGUE_LEFT" value="90" enum="BlendShapeEntry"> + Tongue points left. + </constant> + <constant name="FT_TONGUE_ROLL" value="91" enum="BlendShapeEntry"> + Sides of the tongue funnel, creating a roll. + </constant> + <constant name="FT_TONGUE_BLEND_DOWN" value="92" enum="BlendShapeEntry"> + Tongue arches up then down inside the mouth. + </constant> + <constant name="FT_TONGUE_CURL_UP" value="93" enum="BlendShapeEntry"> + Tongue arches down then up inside the mouth. + </constant> + <constant name="FT_TONGUE_SQUISH" value="94" enum="BlendShapeEntry"> + Tongue squishes together and thickens. + </constant> + <constant name="FT_TONGUE_FLAT" value="95" enum="BlendShapeEntry"> + Tongue flattens and thins out. + </constant> + <constant name="FT_TONGUE_TWIST_RIGHT" value="96" enum="BlendShapeEntry"> + Tongue tip rotates clockwise, with the rest following gradually. + </constant> + <constant name="FT_TONGUE_TWIST_LEFT" value="97" enum="BlendShapeEntry"> + Tongue tip rotates counter-clockwise, with the rest following gradually. + </constant> + <constant name="FT_SOFT_PALATE_CLOSE" value="98" enum="BlendShapeEntry"> + Inner mouth throat closes. + </constant> + <constant name="FT_THROAT_SWALLOW" value="99" enum="BlendShapeEntry"> + The Adam's apple visibly swallows. + </constant> + <constant name="FT_NECK_FLEX_RIGHT" value="100" enum="BlendShapeEntry"> + Right side neck visibly flexes. + </constant> + <constant name="FT_NECK_FLEX_LEFT" value="101" enum="BlendShapeEntry"> + Left side neck visibly flexes. + </constant> + <constant name="FT_EYE_CLOSED" value="102" enum="BlendShapeEntry"> + Closes both eye lids. + </constant> + <constant name="FT_EYE_WIDE" value="103" enum="BlendShapeEntry"> + Widens both eye lids. + </constant> + <constant name="FT_EYE_SQUINT" value="104" enum="BlendShapeEntry"> + Squints both eye lids. + </constant> + <constant name="FT_EYE_DILATION" value="105" enum="BlendShapeEntry"> + Dilates both pupils. + </constant> + <constant name="FT_EYE_CONSTRICT" value="106" enum="BlendShapeEntry"> + Constricts both pupils. + </constant> + <constant name="FT_BROW_DOWN_RIGHT" value="107" enum="BlendShapeEntry"> + Pulls the right eyebrow down and in. + </constant> + <constant name="FT_BROW_DOWN_LEFT" value="108" enum="BlendShapeEntry"> + Pulls the left eyebrow down and in. + </constant> + <constant name="FT_BROW_DOWN" value="109" enum="BlendShapeEntry"> + Pulls both eyebrows down and in. + </constant> + <constant name="FT_BROW_UP_RIGHT" value="110" enum="BlendShapeEntry"> + Right brow appears worried. + </constant> + <constant name="FT_BROW_UP_LEFT" value="111" enum="BlendShapeEntry"> + Left brow appears worried. + </constant> + <constant name="FT_BROW_UP" value="112" enum="BlendShapeEntry"> + Both brows appear worried. + </constant> + <constant name="FT_NOSE_SNEER" value="113" enum="BlendShapeEntry"> + Entire face sneers. + </constant> + <constant name="FT_NASAL_DILATION" value="114" enum="BlendShapeEntry"> + Both nose canals dilate. + </constant> + <constant name="FT_NASAL_CONSTRICT" value="115" enum="BlendShapeEntry"> + Both nose canals constrict. + </constant> + <constant name="FT_CHEEK_PUFF" value="116" enum="BlendShapeEntry"> + Puffs both cheeks. + </constant> + <constant name="FT_CHEEK_SUCK" value="117" enum="BlendShapeEntry"> + Sucks in both cheeks. + </constant> + <constant name="FT_CHEEK_SQUINT" value="118" enum="BlendShapeEntry"> + Raises both cheeks. + </constant> + <constant name="FT_LIP_SUCK_UPPER" value="119" enum="BlendShapeEntry"> + Tucks in the upper lips. + </constant> + <constant name="FT_LIP_SUCK_LOWER" value="120" enum="BlendShapeEntry"> + Tucks in the lower lips. + </constant> + <constant name="FT_LIP_SUCK" value="121" enum="BlendShapeEntry"> + Tucks in both lips. + </constant> + <constant name="FT_LIP_FUNNEL_UPPER" value="122" enum="BlendShapeEntry"> + Funnels in the upper lips. + </constant> + <constant name="FT_LIP_FUNNEL_LOWER" value="123" enum="BlendShapeEntry"> + Funnels in the lower lips. + </constant> + <constant name="FT_LIP_FUNNEL" value="124" enum="BlendShapeEntry"> + Funnels in both lips. + </constant> + <constant name="FT_LIP_PUCKER_UPPER" value="125" enum="BlendShapeEntry"> + Upper lip part pushes outwards. + </constant> + <constant name="FT_LIP_PUCKER_LOWER" value="126" enum="BlendShapeEntry"> + Lower lip part pushes outwards. + </constant> + <constant name="FT_LIP_PUCKER" value="127" enum="BlendShapeEntry"> + Lips push outwards. + </constant> + <constant name="FT_MOUTH_UPPER_UP" value="128" enum="BlendShapeEntry"> + Raises the upper lips. + </constant> + <constant name="FT_MOUTH_LOWER_DOWN" value="129" enum="BlendShapeEntry"> + Lowers the lower lips. + </constant> + <constant name="FT_MOUTH_OPEN" value="130" enum="BlendShapeEntry"> + Mouth opens, revealing teeth. + </constant> + <constant name="FT_MOUTH_RIGHT" value="131" enum="BlendShapeEntry"> + Moves mouth right. + </constant> + <constant name="FT_MOUTH_LEFT" value="132" enum="BlendShapeEntry"> + Moves mouth left. + </constant> + <constant name="FT_MOUTH_SMILE_RIGHT" value="133" enum="BlendShapeEntry"> + Right side of the mouth smiles. + </constant> + <constant name="FT_MOUTH_SMILE_LEFT" value="134" enum="BlendShapeEntry"> + Left side of the mouth smiles. + </constant> + <constant name="FT_MOUTH_SMILE" value="135" enum="BlendShapeEntry"> + Mouth expresses a smile. + </constant> + <constant name="FT_MOUTH_SAD_RIGHT" value="136" enum="BlendShapeEntry"> + Right side of the mouth expresses sadness. + </constant> + <constant name="FT_MOUTH_SAD_LEFT" value="137" enum="BlendShapeEntry"> + Left side of the mouth expresses sadness. + </constant> + <constant name="FT_MOUTH_SAD" value="138" enum="BlendShapeEntry"> + Mouth expresses sadness. + </constant> + <constant name="FT_MOUTH_STRETCH" value="139" enum="BlendShapeEntry"> + Mouth stretches. + </constant> + <constant name="FT_MOUTH_DIMPLE" value="140" enum="BlendShapeEntry"> + Lip corners dimple. + </constant> + <constant name="FT_MOUTH_TIGHTENER" value="141" enum="BlendShapeEntry"> + Mouth tightens. + </constant> + <constant name="FT_MOUTH_PRESS" value="142" enum="BlendShapeEntry"> + Mouth presses together. + </constant> + <constant name="FT_MAX" value="143" enum="BlendShapeEntry"> + Represents the size of the [enum BlendShapeEntry] enum. + </constant> + </constants> +</class> diff --git a/doc/classes/XRHandModifier3D.xml b/doc/classes/XRHandModifier3D.xml new file mode 100644 index 0000000000..9ff27bb982 --- /dev/null +++ b/doc/classes/XRHandModifier3D.xml @@ -0,0 +1,33 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="XRHandModifier3D" inherits="SkeletonModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A node for driving hand meshes from [XRHandTracker] data. + </brief_description> + <description> + This node uses hand tracking data from a [XRHandTracker] to animate the skeleton of a hand mesh. + This node positions itself at the [constant XRHandTracker.HAND_JOINT_PALM] position and scales itself to [member XRServer.world_scale]. Adding the hand model as a child of this node will result in the model being positioned and scaled correctly for XR experiences. + The hand tracking position-data is scaled by [member Skeleton3D.motion_scale] when applied to the skeleton, which can be used to adjust the tracked hand to match the scale of the hand model. + </description> + <tutorials> + <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> + </tutorials> + <members> + <member name="bone_update" type="int" setter="set_bone_update" getter="get_bone_update" enum="XRHandModifier3D.BoneUpdate" default="0"> + Specifies the type of updates to perform on the bones. + </member> + <member name="hand_tracker" type="StringName" setter="set_hand_tracker" getter="get_hand_tracker" default="&"/user/left""> + The name of the [XRHandTracker] registered with [XRServer] to obtain the hand tracking data from. + </member> + </members> + <constants> + <constant name="BONE_UPDATE_FULL" value="0" enum="BoneUpdate"> + The skeleton's bones are fully updated (both position and rotation) to match the tracked bones. + </constant> + <constant name="BONE_UPDATE_ROTATION_ONLY" value="1" enum="BoneUpdate"> + The skeleton's bones are only rotated to align with the tracked bones, preserving bone length. + </constant> + <constant name="BONE_UPDATE_MAX" value="2" enum="BoneUpdate"> + Represents the size of the [enum BoneUpdate] enum. + </constant> + </constants> +</class> diff --git a/doc/classes/XRHandTracker.xml b/doc/classes/XRHandTracker.xml new file mode 100644 index 0000000000..932fec083a --- /dev/null +++ b/doc/classes/XRHandTracker.xml @@ -0,0 +1,223 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="XRHandTracker" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A tracked hand in XR. + </brief_description> + <description> + A hand tracking system will create an instance of this object and add it to the [XRServer]. This tracking system will then obtain skeleton data, convert it to the Godot Humanoid hand skeleton and store this data on the [XRHandTracker] object. + Use [XRHandModifier3D] to animate a hand mesh using hand tracking data. + </description> + <tutorials> + <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> + </tutorials> + <methods> + <method name="get_hand_joint_angular_velocity" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <description> + Returns the angular velocity for the given hand joint. + </description> + </method> + <method name="get_hand_joint_flags" qualifiers="const"> + <return type="int" enum="XRHandTracker.HandJointFlags" is_bitfield="true" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <description> + Returns flags about the validity of the tracking data for the given hand joint (see [enum XRHandTracker.HandJointFlags]). + </description> + </method> + <method name="get_hand_joint_linear_velocity" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <description> + Returns the linear velocity for the given hand joint. + </description> + </method> + <method name="get_hand_joint_radius" qualifiers="const"> + <return type="float" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <description> + Returns the radius of the given hand joint. + </description> + </method> + <method name="get_hand_joint_transform" qualifiers="const"> + <return type="Transform3D" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <description> + Returns the transform for the given hand joint. + </description> + </method> + <method name="set_hand_joint_angular_velocity"> + <return type="void" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <param index="1" name="angular_velocity" type="Vector3" /> + <description> + Sets the angular velocity for the given hand joint. + </description> + </method> + <method name="set_hand_joint_flags"> + <return type="void" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <param index="1" name="flags" type="int" enum="XRHandTracker.HandJointFlags" is_bitfield="true" /> + <description> + Sets flags about the validity of the tracking data for the given hand joint. + </description> + </method> + <method name="set_hand_joint_linear_velocity"> + <return type="void" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <param index="1" name="linear_velocity" type="Vector3" /> + <description> + Sets the linear velocity for the given hand joint. + </description> + </method> + <method name="set_hand_joint_radius"> + <return type="void" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <param index="1" name="radius" type="float" /> + <description> + Sets the radius of the given hand joint. + </description> + </method> + <method name="set_hand_joint_transform"> + <return type="void" /> + <param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" /> + <param index="1" name="transform" type="Transform3D" /> + <description> + Sets the transform for the given hand joint. + </description> + </method> + </methods> + <members> + <member name="hand" type="int" setter="set_hand" getter="get_hand" enum="XRHandTracker.Hand" default="0"> + The type of hand. + </member> + <member name="hand_tracking_source" type="int" setter="set_hand_tracking_source" getter="get_hand_tracking_source" enum="XRHandTracker.HandTrackingSource" default="0"> + The source of the hand tracking data. + </member> + <member name="has_tracking_data" type="bool" setter="set_has_tracking_data" getter="get_has_tracking_data" default="false"> + If [code]true[/code], the hand tracking data is valid. + </member> + </members> + <constants> + <constant name="HAND_LEFT" value="0" enum="Hand"> + A left hand. + </constant> + <constant name="HAND_RIGHT" value="1" enum="Hand"> + A right hand. + </constant> + <constant name="HAND_MAX" value="2" enum="Hand"> + Represents the size of the [enum Hand] enum. + </constant> + <constant name="HAND_TRACKING_SOURCE_UNKNOWN" value="0" enum="HandTrackingSource"> + The source of hand tracking data is unknown. + </constant> + <constant name="HAND_TRACKING_SOURCE_UNOBSTRUCTED" value="1" enum="HandTrackingSource"> + The source of hand tracking data is unobstructed, meaning that an accurate method of hand tracking is used. These include optical hand tracking, data gloves, etc. + </constant> + <constant name="HAND_TRACKING_SOURCE_CONTROLLER" value="2" enum="HandTrackingSource"> + The source of hand tracking data is a controller, meaning that joint positions are inferred from controller inputs. + </constant> + <constant name="HAND_TRACKING_SOURCE_MAX" value="3" enum="HandTrackingSource"> + Represents the size of the [enum HandTrackingSource] enum. + </constant> + <constant name="HAND_JOINT_PALM" value="0" enum="HandJoint"> + Palm joint. + </constant> + <constant name="HAND_JOINT_WRIST" value="1" enum="HandJoint"> + Wrist joint. + </constant> + <constant name="HAND_JOINT_THUMB_METACARPAL" value="2" enum="HandJoint"> + Thumb metacarpal joint. + </constant> + <constant name="HAND_JOINT_THUMB_PHALANX_PROXIMAL" value="3" enum="HandJoint"> + Thumb phalanx proximal joint. + </constant> + <constant name="HAND_JOINT_THUMB_PHALANX_DISTAL" value="4" enum="HandJoint"> + Thumb phalanx distal joint. + </constant> + <constant name="HAND_JOINT_THUMB_TIP" value="5" enum="HandJoint"> + Thumb tip joint. + </constant> + <constant name="HAND_JOINT_INDEX_FINGER_METACARPAL" value="6" enum="HandJoint"> + Index finger metacarpal joint. + </constant> + <constant name="HAND_JOINT_INDEX_FINGER_PHALANX_PROXIMAL" value="7" enum="HandJoint"> + Index finger phalanx proximal joint. + </constant> + <constant name="HAND_JOINT_INDEX_FINGER_PHALANX_INTERMEDIATE" value="8" enum="HandJoint"> + Index finger phalanx intermediate joint. + </constant> + <constant name="HAND_JOINT_INDEX_FINGER_PHALANX_DISTAL" value="9" enum="HandJoint"> + Index finger phalanx distal joint. + </constant> + <constant name="HAND_JOINT_INDEX_FINGER_TIP" value="10" enum="HandJoint"> + Index finger tip joint. + </constant> + <constant name="HAND_JOINT_MIDDLE_FINGER_METACARPAL" value="11" enum="HandJoint"> + Middle finger metacarpal joint. + </constant> + <constant name="HAND_JOINT_MIDDLE_FINGER_PHALANX_PROXIMAL" value="12" enum="HandJoint"> + Middle finger phalanx proximal joint. + </constant> + <constant name="HAND_JOINT_MIDDLE_FINGER_PHALANX_INTERMEDIATE" value="13" enum="HandJoint"> + Middle finger phalanx intermediate joint. + </constant> + <constant name="HAND_JOINT_MIDDLE_FINGER_PHALANX_DISTAL" value="14" enum="HandJoint"> + Middle finger phalanx distal joint. + </constant> + <constant name="HAND_JOINT_MIDDLE_FINGER_TIP" value="15" enum="HandJoint"> + Middle finger tip joint. + </constant> + <constant name="HAND_JOINT_RING_FINGER_METACARPAL" value="16" enum="HandJoint"> + Ring finger metacarpal joint. + </constant> + <constant name="HAND_JOINT_RING_FINGER_PHALANX_PROXIMAL" value="17" enum="HandJoint"> + Ring finger phalanx proximal joint. + </constant> + <constant name="HAND_JOINT_RING_FINGER_PHALANX_INTERMEDIATE" value="18" enum="HandJoint"> + Ring finger phalanx intermediate joint. + </constant> + <constant name="HAND_JOINT_RING_FINGER_PHALANX_DISTAL" value="19" enum="HandJoint"> + Ring finger phalanx distal joint. + </constant> + <constant name="HAND_JOINT_RING_FINGER_TIP" value="20" enum="HandJoint"> + Ring finger tip joint. + </constant> + <constant name="HAND_JOINT_PINKY_FINGER_METACARPAL" value="21" enum="HandJoint"> + Pinky finger metacarpal joint. + </constant> + <constant name="HAND_JOINT_PINKY_FINGER_PHALANX_PROXIMAL" value="22" enum="HandJoint"> + Pinky finger phalanx proximal joint. + </constant> + <constant name="HAND_JOINT_PINKY_FINGER_PHALANX_INTERMEDIATE" value="23" enum="HandJoint"> + Pinky finger phalanx intermediate joint. + </constant> + <constant name="HAND_JOINT_PINKY_FINGER_PHALANX_DISTAL" value="24" enum="HandJoint"> + Pinky finger phalanx distal joint. + </constant> + <constant name="HAND_JOINT_PINKY_FINGER_TIP" value="25" enum="HandJoint"> + Pinky finger tip joint. + </constant> + <constant name="HAND_JOINT_MAX" value="26" enum="HandJoint"> + Represents the size of the [enum HandJoint] enum. + </constant> + <constant name="HAND_JOINT_FLAG_ORIENTATION_VALID" value="1" enum="HandJointFlags" is_bitfield="true"> + The hand joint's orientation data is valid. + </constant> + <constant name="HAND_JOINT_FLAG_ORIENTATION_TRACKED" value="2" enum="HandJointFlags" is_bitfield="true"> + The hand joint's orientation is actively tracked. May not be set if tracking has been temporarily lost. + </constant> + <constant name="HAND_JOINT_FLAG_POSITION_VALID" value="4" enum="HandJointFlags" is_bitfield="true"> + The hand joint's position data is valid. + </constant> + <constant name="HAND_JOINT_FLAG_POSITION_TRACKED" value="8" enum="HandJointFlags" is_bitfield="true"> + The hand joint's position is actively tracked. May not be set if tracking has been temporarily lost. + </constant> + <constant name="HAND_JOINT_FLAG_LINEAR_VELOCITY_VALID" value="16" enum="HandJointFlags" is_bitfield="true"> + The hand joint's linear velocity data is valid. + </constant> + <constant name="HAND_JOINT_FLAG_ANGULAR_VELOCITY_VALID" value="32" enum="HandJointFlags" is_bitfield="true"> + The hand joint's angular velocity data is valid. + </constant> + </constants> +</class> diff --git a/doc/classes/XRInterface.xml b/doc/classes/XRInterface.xml index 99d6e67e51..175caca598 100644 --- a/doc/classes/XRInterface.xml +++ b/doc/classes/XRInterface.xml @@ -26,13 +26,13 @@ <method name="get_name" qualifiers="const"> <return type="StringName" /> <description> - Returns the name of this interface (OpenXR, OpenVR, OpenHMD, ARKit, etc). + Returns the name of this interface ([code]"OpenXR"[/code], [code]"OpenVR"[/code], [code]"OpenHMD"[/code], [code]"ARKit"[/code], etc.). </description> </method> <method name="get_play_area" qualifiers="const"> <return type="PackedVector3Array" /> <description> - Returns an array of vectors that denotes the physical play area mapped to the virtual space around the [XROrigin3D] point. The points form a convex polygon that can be used to react to or visualize the play area. This returns an empty array if this feature is not supported or if the information is not yet available. + Returns an array of vectors that represent the physical play area mapped to the virtual space around the [XROrigin3D] point. The points form a convex polygon that can be used to react to or visualize the play area. This returns an empty array if this feature is not supported or if the information is not yet available. </description> </method> <method name="get_projection_for_view"> @@ -99,19 +99,19 @@ <method name="is_initialized" qualifiers="const"> <return type="bool" /> <description> - Is [code]true[/code] if this interface has been initialized. + Returns [code]true[/code] if this interface has been initialized. </description> </method> - <method name="is_passthrough_enabled"> + <method name="is_passthrough_enabled" deprecated="Check if [member environment_blend_mode] is [constant XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND], instead."> <return type="bool" /> <description> - Is [code]true[/code] if passthrough is enabled. + Returns [code]true[/code] if passthrough is enabled. </description> </method> - <method name="is_passthrough_supported"> + <method name="is_passthrough_supported" deprecated="Check that [constant XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND] is supported using [method get_supported_environment_blend_modes], instead."> <return type="bool" /> <description> - Is [code]true[/code] if this interface supports passthrough. + Returns [code]true[/code] if this interface supports passthrough. </description> </method> <method name="set_environment_blend_mode"> @@ -119,20 +119,20 @@ <param index="0" name="mode" type="int" enum="XRInterface.EnvironmentBlendMode" /> <description> Sets the active environment blend mode. - [param mode] is the [enum XRInterface.EnvironmentBlendMode] starting with the next frame. + [param mode] is the environment blend mode starting with the next frame. [b]Note:[/b] Not all runtimes support all environment blend modes, so it is important to check this at startup. For example: [codeblock] - func _ready(): - var xr_interface: XRInterface = XRServer.find_interface("OpenXR") - if xr_interface and xr_interface.is_initialized(): - var vp: Viewport = get_viewport() - vp.use_xr = true - var acceptable_modes = [ XRInterface.XR_ENV_BLEND_MODE_OPAQUE, XRInterface.XR_ENV_BLEND_MODE_ADDITIVE ] - var modes = xr_interface.get_supported_environment_blend_modes() - for mode in acceptable_modes: - if mode in modes: - xr_interface.set_environment_blend_mode(mode) - break + func _ready(): + var xr_interface: XRInterface = XRServer.find_interface("OpenXR") + if xr_interface and xr_interface.is_initialized(): + var vp: Viewport = get_viewport() + vp.use_xr = true + var acceptable_modes = [XRInterface.XR_ENV_BLEND_MODE_OPAQUE, XRInterface.XR_ENV_BLEND_MODE_ADDITIVE] + var modes = xr_interface.get_supported_environment_blend_modes() + for mode in acceptable_modes: + if mode in modes: + xr_interface.set_environment_blend_mode(mode) + break [/codeblock] </description> </method> @@ -141,16 +141,17 @@ <param index="0" name="mode" type="int" enum="XRInterface.PlayAreaMode" /> <description> Sets the active play area mode, will return [code]false[/code] if the mode can't be used with this interface. + [b]Note:[/b] Changing this after the interface has already been initialized can be jarring for the player, so it's recommended to recenter on the HMD with [method XRServer.center_on_hmd] (if switching to [constant XRInterface.XR_PLAY_AREA_STAGE]) or make the switch during a scene change. </description> </method> - <method name="start_passthrough"> + <method name="start_passthrough" deprecated="Set the [member environment_blend_mode] to [constant XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND], instead."> <return type="bool" /> <description> Starts passthrough, will return [code]false[/code] if passthrough couldn't be started. [b]Note:[/b] The viewport used for XR must have a transparent background, otherwise passthrough may not properly render. </description> </method> - <method name="stop_passthrough"> + <method name="stop_passthrough" deprecated="Set the [member environment_blend_mode] to [constant XRInterface.XR_ENV_BLEND_MODE_OPAQUE], instead."> <return type="void" /> <description> Stops passthrough. @@ -256,7 +257,7 @@ Player is free to move around, full positional tracking. </constant> <constant name="XR_PLAY_AREA_STAGE" value="4" enum="PlayAreaMode"> - Same as [constant XR_PLAY_AREA_ROOMSCALE] but origin point is fixed to the center of the physical space, [method XRServer.center_on_hmd] disabled. + Same as [constant XR_PLAY_AREA_ROOMSCALE] but origin point is fixed to the center of the physical space. In this mode, system-level recentering may be disabled, requiring the use of [method XRServer.center_on_hmd]. </constant> <constant name="XR_ENV_BLEND_MODE_OPAQUE" value="0" enum="EnvironmentBlendMode"> Opaque blend mode. This is typically used for VR devices. diff --git a/doc/classes/XRInterfaceExtension.xml b/doc/classes/XRInterfaceExtension.xml index ea2bbf4cfb..b11c4cbb26 100644 --- a/doc/classes/XRInterfaceExtension.xml +++ b/doc/classes/XRInterfaceExtension.xml @@ -61,13 +61,13 @@ <method name="_get_play_area" qualifiers="virtual const"> <return type="PackedVector3Array" /> <description> - Returns an [PackedVector3Array] that denotes the play areas boundaries (if applicable). + Returns a [PackedVector3Array] that represents the play areas boundaries (if applicable). </description> </method> <method name="_get_play_area_mode" qualifiers="virtual const"> <return type="int" enum="XRInterface.PlayAreaMode" /> <description> - Returns the [enum XRInterface.PlayAreaMode] that sets up our play area. + Returns the play area mode that sets up our play area. </description> </method> <method name="_get_projection_for_view" qualifiers="virtual"> diff --git a/doc/classes/XROrigin3D.xml b/doc/classes/XROrigin3D.xml index b35d27ab12..041e8cd7aa 100644 --- a/doc/classes/XROrigin3D.xml +++ b/doc/classes/XROrigin3D.xml @@ -5,20 +5,19 @@ </brief_description> <description> This is a special node within the AR/VR system that maps the physical location of the center of our tracking space to the virtual location within our game world. - There should be only one of these nodes in your scene and you must have one. All the XRCamera3D, XRController3D and XRAnchor3D nodes should be direct children of this node for spatial tracking to work correctly. + Multiple origin points can be added to the scene tree, but only one can used at a time. All the [XRCamera3D], [XRController3D], and [XRAnchor3D] nodes should be direct children of this node for spatial tracking to work correctly. It is the position of this node that you update when your character needs to move through your game world while we're not moving in the real world. Movement in the real world is always in relation to this origin point. - For example, if your character is driving a car, the XROrigin3D node should be a child node of this car. Or, if you're implementing a teleport system to move your character, you should change the position of this node. + For example, if your character is driving a car, the [XROrigin3D] node should be a child node of this car. Or, if you're implementing a teleport system to move your character, you should change the position of this node. </description> <tutorials> <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> </tutorials> <members> <member name="current" type="bool" setter="set_current" getter="is_current" default="false"> - Is this XROrigin3D node the current origin used by the [XRServer]? + If [code]true[/code], this origin node is currently being used by the [XRServer]. Only one origin point can be used at a time. </member> <member name="world_scale" type="float" setter="set_world_scale" getter="get_world_scale" default="1.0"> - Allows you to adjust the scale to your game's units. Most AR/VR platforms assume a scale of 1 game world unit = 1 real world meter. - [b]Note:[/b] This method is a passthrough to the [XRServer] itself. + The scale of the game world compared to the real world. This is the same as [member XRServer.world_scale]. By default, most AR/VR platforms assume that 1 game unit corresponds to 1 real world meter. </member> </members> </class> diff --git a/doc/classes/XRPose.xml b/doc/classes/XRPose.xml index f7bfcf4e38..60a2226a60 100644 --- a/doc/classes/XRPose.xml +++ b/doc/classes/XRPose.xml @@ -50,7 +50,7 @@ Tracking information may be inaccurate or estimated. For example, with inside out tracking this would indicate a controller may be (partially) obscured. </constant> <constant name="XR_TRACKING_CONFIDENCE_HIGH" value="2" enum="TrackingConfidence"> - Tracking information is deemed accurate and up to date. + Tracking information is considered accurate and up to date. </constant> </constants> </class> diff --git a/doc/classes/XRServer.xml b/doc/classes/XRServer.xml index 4ef5d3473b..671cc8f15c 100644 --- a/doc/classes/XRServer.xml +++ b/doc/classes/XRServer.xml @@ -10,6 +10,30 @@ <link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link> </tutorials> <methods> + <method name="add_body_tracker"> + <return type="void" /> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="body_tracker" type="XRBodyTracker" /> + <description> + Registers a new [XRBodyTracker] that tracks the joints of a body. + </description> + </method> + <method name="add_face_tracker"> + <return type="void" /> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="face_tracker" type="XRFaceTracker" /> + <description> + Registers a new [XRFaceTracker] that tracks the blend shapes of a face. + </description> + </method> + <method name="add_hand_tracker"> + <return type="void" /> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="hand_tracker" type="XRHandTracker" /> + <description> + Registers a new [XRHandTracker] that tracks the joints of a hand. + </description> + </method> <method name="add_interface"> <return type="void" /> <param index="0" name="interface" type="XRInterface" /> @@ -37,6 +61,12 @@ You should call this method after a few seconds have passed. For example, when the user requests a realignment of the display holding a designated button on a controller for a short period of time, or when implementing a teleport mechanism. </description> </method> + <method name="clear_reference_frame" qualifiers="const"> + <return type="Transform3D" /> + <description> + Clears the reference frame that was set by previous calls to [method center_on_hmd]. + </description> + </method> <method name="find_interface" qualifiers="const"> <return type="XRInterface" /> <param index="0" name="name" type="String" /> @@ -44,6 +74,45 @@ Finds an interface by its [param name]. For example, if your project uses capabilities of an AR/VR platform, you can find the interface for that platform by name and initialize it. </description> </method> + <method name="get_body_tracker" qualifiers="const"> + <return type="XRBodyTracker" /> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Returns the [XRBodyTracker] with the given tracker name. + </description> + </method> + <method name="get_body_trackers" qualifiers="const"> + <return type="Dictionary" /> + <description> + Returns a dictionary of the registered body trackers. Each element of the dictionary is a tracker name mapping to the [XRBodyTracker] instance. + </description> + </method> + <method name="get_face_tracker" qualifiers="const"> + <return type="XRFaceTracker" /> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Returns the [XRFaceTracker] with the given tracker name. + </description> + </method> + <method name="get_face_trackers" qualifiers="const"> + <return type="Dictionary" /> + <description> + Returns a dictionary of the registered face trackers. Each element of the dictionary is a tracker name mapping to the [XRFaceTracker] instance. + </description> + </method> + <method name="get_hand_tracker" qualifiers="const"> + <return type="XRHandTracker" /> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Returns the [XRHandTracker] with the given tracker name. + </description> + </method> + <method name="get_hand_trackers" qualifiers="const"> + <return type="Dictionary" /> + <description> + Returns a dictionary of the registered hand trackers. Each element of the dictionary is a tracker name mapping to the [XRHandTracker] instance. + </description> + </method> <method name="get_hmd_transform"> <return type="Transform3D" /> <description> @@ -89,6 +158,27 @@ Returns a dictionary of trackers for [param tracker_types]. </description> </method> + <method name="remove_body_tracker"> + <return type="void" /> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Removes a registered [XRBodyTracker]. + </description> + </method> + <method name="remove_face_tracker"> + <return type="void" /> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Removes a registered [XRFaceTracker]. + </description> + </method> + <method name="remove_hand_tracker"> + <return type="void" /> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Removes a registered [XRHandTracker]. + </description> + </method> <method name="remove_interface"> <return type="void" /> <param index="0" name="interface" type="XRInterface" /> @@ -113,10 +203,70 @@ [b]Note:[/b] This property is managed by the current [XROrigin3D] node. It is exposed for access from GDExtensions. </member> <member name="world_scale" type="float" setter="set_world_scale" getter="get_world_scale" default="1.0"> - Allows you to adjust the scale to your game's units. Most AR/VR platforms assume a scale of 1 game world unit = 1 real world meter. + The scale of the game world compared to the real world. By default, most AR/VR platforms assume that 1 game unit corresponds to 1 real world meter. </member> </members> <signals> + <signal name="body_tracker_added"> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="body_tracker" type="XRBodyTracker" /> + <description> + Emitted when a new body tracker is added. + </description> + </signal> + <signal name="body_tracker_removed"> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Emitted when a body tracker is removed. + </description> + </signal> + <signal name="body_tracker_updated"> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="body_tracker" type="XRBodyTracker" /> + <description> + Emitted when an existing body tracker is updated. + </description> + </signal> + <signal name="face_tracker_added"> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="face_tracker" type="XRFaceTracker" /> + <description> + Emitted when a new face tracker is added. + </description> + </signal> + <signal name="face_tracker_removed"> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Emitted when a face tracker is removed. + </description> + </signal> + <signal name="face_tracker_updated"> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="face_tracker" type="XRFaceTracker" /> + <description> + Emitted when an existing face tracker is updated. + </description> + </signal> + <signal name="hand_tracker_added"> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="hand_tracker" type="XRHandTracker" /> + <description> + Emitted when a new hand tracker is added. + </description> + </signal> + <signal name="hand_tracker_removed"> + <param index="0" name="tracker_name" type="StringName" /> + <description> + Emitted when a hand tracker is removed. + </description> + </signal> + <signal name="hand_tracker_updated"> + <param index="0" name="tracker_name" type="StringName" /> + <param index="1" name="hand_tracker" type="XRHandTracker" /> + <description> + Emitted when an existing hand tracker is updated. + </description> + </signal> <signal name="interface_added"> <param index="0" name="interface_name" type="StringName" /> <description> diff --git a/doc/classes/float.xml b/doc/classes/float.xml index 3ffaa60c32..56f78bdc8a 100644 --- a/doc/classes/float.xml +++ b/doc/classes/float.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="float" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - A built-in type for floating point numbers. + A built-in type for floating-point numbers. </brief_description> <description> The [float] built-in type is a 64-bit double-precision floating-point number, equivalent to [code]double[/code] in C++. This type has 14 reliable decimal digits of precision. The maximum value of [float] is approximately [code]1.79769e308[/code], and the minimum is approximately [code]-1.79769e308[/code]. diff --git a/doc/classes/int.xml b/doc/classes/int.xml index 9d168c60e2..c38b0fa38e 100644 --- a/doc/classes/int.xml +++ b/doc/classes/int.xml @@ -6,7 +6,7 @@ <description> Signed 64-bit integer type. This means that it can take values from [code]-2^63[/code] to [code]2^63 - 1[/code], i.e. from [code]-9223372036854775808[/code] to [code]9223372036854775807[/code]. When it exceeds these bounds, it will wrap around. [int]s can be automatically converted to [float]s when necessary, for example when passing them as arguments in functions. The [float] will be as close to the original integer as possible. - Likewise, [float]s can be automatically converted into [int]s. This will truncate the [float], discarding anything after the floating point. + Likewise, [float]s can be automatically converted into [int]s. This will truncate the [float], discarding anything after the floating-point. [b]Note:[/b] In a boolean context, an [int] will evaluate to [code]false[/code] if it equals [code]0[/code], and to [code]true[/code] otherwise. [codeblocks] [gdscript] |