diff options
Diffstat (limited to 'doc/classes')
53 files changed, 2329 insertions, 495 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index ee65bbc07e..f6b8e0da19 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -10,6 +10,1147 @@ <tutorials> </tutorials> <methods> + <method name="abs"> + <return type="Variant"> + </return> + <argument index="0" name="x" type="Variant"> + </argument> + <description> + </description> + </method> + <method name="absf"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the absolute value of float parameter [code]x[/code] (i.e. positive value). + [codeblock] + # a is 1.2 + a = absf(-1.2) + [/codeblock] + </description> + </method> + <method name="absi"> + <return type="int"> + </return> + <argument index="0" name="x" type="int"> + </argument> + <description> + Returns the absolute value of int parameter [code]x[/code] (i.e. positive value). + [codeblock] + # a is 1 + a = absi(-1) + [/codeblock] + </description> + </method> + <method name="acos"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the arc cosine of [code]x[/code] in radians. Use to get the angle of cosine [code]x[/code]. + [codeblock] + # c is 0.523599 or 30 degrees if converted with rad2deg(c) + c = acos(0.866025) + [/codeblock] + </description> + </method> + <method name="asin"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the arc sine of [code]x[/code] in radians. Use to get the angle of sine [code]x[/code]. + [codeblock] + # s is 0.523599 or 30 degrees if converted with rad2deg(s) + s = asin(0.5) + [/codeblock] + </description> + </method> + <method name="atan"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the arc tangent of [code]x[/code] in radians. Use it to get the angle from an angle's tangent in trigonometry: [code]atan(tan(angle)) == angle[/code]. + The method cannot know in which quadrant the angle should fall. See [method atan2] if you have both [code]y[/code] and [code]x[/code]. + [codeblock] + a = atan(0.5) # a is 0.463648 + [/codeblock] + </description> + </method> + <method name="atan2"> + <return type="float"> + </return> + <argument index="0" name="y" type="float"> + </argument> + <argument index="1" name="x" type="float"> + </argument> + <description> + Returns the arc tangent of [code]y/x[/code] in radians. Use to get the angle of tangent [code]y/x[/code]. To compute the value, the method takes into account the sign of both arguments in order to determine the quadrant. + Important note: The Y coordinate comes first, by convention. + [codeblock] + a = atan2(0, -1) # a is 3.141593 + [/codeblock] + </description> + </method> + <method name="bytes2var"> + <return type="Variant"> + </return> + <argument index="0" name="bytes" type="PackedByteArray"> + </argument> + <description> + Decodes a byte array back to a [Variant] value, without decoding objects. + [b]Note:[/b] If you need object deserialization, see [method bytes2var_with_objects]. + </description> + </method> + <method name="bytes2var_with_objects"> + <return type="Variant"> + </return> + <argument index="0" name="bytes" type="PackedByteArray"> + </argument> + <description> + Decodes a byte array back to a [Variant] value. Decoding objects is allowed. + [b]WARNING:[/b] Deserialized object can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats (remote code execution). + </description> + </method> + <method name="cartesian2polar"> + <return type="Vector2"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <argument index="1" name="y" type="float"> + </argument> + <description> + Converts a 2D point expressed in the cartesian coordinate system (X and Y axis) to the polar coordinate system (a distance from the origin and an angle). + </description> + </method> + <method name="ceil"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Rounds [code]x[/code] upward (towards positive infinity), returning the smallest whole number that is not less than [code]x[/code]. + [codeblock] + i = ceil(1.45) # i is 2 + i = ceil(1.001) # i is 2 + [/codeblock] + See also [method floor], [method round], and [method stepify]. + </description> + </method> + <method name="clamp"> + <return type="Variant"> + </return> + <argument index="0" name="value" type="Variant"> + </argument> + <argument index="1" name="min" type="Variant"> + </argument> + <argument index="2" name="max" type="Variant"> + </argument> + <description> + </description> + </method> + <method name="clampf"> + <return type="float"> + </return> + <argument index="0" name="value" type="float"> + </argument> + <argument index="1" name="min" type="float"> + </argument> + <argument index="2" name="max" type="float"> + </argument> + <description> + Clamps the float [code]value[/code] and returns a value not less than [code]min[/code] and not more than [code]max[/code]. + [codeblock] + speed = 42.1 + # a is 20.0 + a = clampf(speed, 1.0, 20.0) + + speed = -10.0 + # a is -1.0 + a = clampf(speed, -1.0, 1.0) + [/codeblock] + </description> + </method> + <method name="clampi"> + <return type="int"> + </return> + <argument index="0" name="value" type="int"> + </argument> + <argument index="1" name="min" type="int"> + </argument> + <argument index="2" name="max" type="int"> + </argument> + <description> + Clamps the integer [code]value[/code] and returns a value not less than [code]min[/code] and not more than [code]max[/code]. + [codeblock] + speed = 42 + # a is 20 + a = clampi(speed, 1, 20) + + speed = -10 + # a is -1 + a = clampi(speed, -1, 1) + [/codeblock] + </description> + </method> + <method name="cos"> + <return type="float"> + </return> + <argument index="0" name="angle_rad" type="float"> + </argument> + <description> + Returns the cosine of angle [code]angle_rad[/code] in radians. + [codeblock] + # Prints 1 then -1 + print(cos(PI * 2)) + print(cos(PI)) + [/codeblock] + </description> + </method> + <method name="cosh"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the hyperbolic cosine of [code]x[/code] in radians. + [codeblock] + # Prints 1.543081 + print(cosh(1)) + [/codeblock] + </description> + </method> + <method name="db2linear"> + <return type="float"> + </return> + <argument index="0" name="db" type="float"> + </argument> + <description> + Converts from decibels to linear energy (audio). + </description> + </method> + <method name="dectime"> + <return type="float"> + </return> + <argument index="0" name="value" type="float"> + </argument> + <argument index="1" name="amount" type="float"> + </argument> + <argument index="2" name="step" type="float"> + </argument> + <description> + Returns the result of [code]value[/code] decreased by [code]step[/code] * [code]amount[/code]. + [codeblock] + # a = 59 + a = dectime(60, 10, 0.1)) + [/codeblock] + </description> + </method> + <method name="deg2rad"> + <return type="float"> + </return> + <argument index="0" name="deg" type="float"> + </argument> + <description> + Converts an angle expressed in degrees to radians. + [codeblock] + # r is 3.141593 + r = deg2rad(180) + [/codeblock] + </description> + </method> + <method name="ease"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <argument index="1" name="curve" type="float"> + </argument> + <description> + Easing function, based on exponent. The curve values are: 0 is constant, 1 is linear, 0 to 1 is ease-in, 1+ is ease out. Negative values are in-out/out in. + </description> + </method> + <method name="exp"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + The natural exponential function. It raises the mathematical constant [b]e[/b] to the power of [code]x[/code] and returns it. + [b]e[/b] has an approximate value of 2.71828, and can be obtained with [code]exp(1)[/code]. + For exponents to other bases use the method [method pow]. + [codeblock] + a = exp(2) # Approximately 7.39 + [/codeblock] + </description> + </method> + <method name="floor"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Rounds [code]x[/code] downward (towards negative infinity), returning the largest whole number that is not more than [code]x[/code]. + [codeblock] + # a is 2.0 + a = floor(2.99) + # a is -3.0 + a = floor(-2.99) + [/codeblock] + See also [method ceil], [method round], and [method stepify]. + [b]Note:[/b] This method returns a float. If you need an integer, you can use [code]int(x)[/code] directly. + </description> + </method> + <method name="fmod"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <argument index="1" name="y" type="float"> + </argument> + <description> + Returns the floating-point remainder of [code]x/y[/code], keeping the sign of [code]x[/code]. + [codeblock] + # Remainder is 1.5 + var remainder = fmod(7, 5.5) + [/codeblock] + For the integer remainder operation, use the [code]%[/code] operator. + </description> + </method> + <method name="fposmod"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <argument index="1" name="y" type="float"> + </argument> + <description> + Returns the floating-point modulus of [code]x/y[/code] that wraps equally in positive and negative. + [codeblock] + for i in 7: + var x = 0.5 * i - 1.5 + print("%4.1f %4.1f %4.1f" % [x, fmod(x, 1.5), fposmod(x, 1.5)]) + [/codeblock] + Produces: + [codeblock] + -1.5 -0.0 0.0 + -1.0 -1.0 0.5 + -0.5 -0.5 1.0 + 0.0 0.0 0.0 + 0.5 0.5 0.5 + 1.0 1.0 1.0 + 1.5 0.0 0.0 + [/codeblock] + </description> + </method> + <method name="hash"> + <return type="int"> + </return> + <argument index="0" name="variable" type="Variant"> + </argument> + <description> + Returns the integer hash of the variable passed. + [codeblock] + print(hash("a")) # Prints 177670 + [/codeblock] + </description> + </method> + <method name="instance_from_id"> + <return type="Object"> + </return> + <argument index="0" name="instance_id" type="int"> + </argument> + <description> + Returns the Object that corresponds to [code]instance_id[/code]. All Objects have a unique instance ID. + [codeblock] + var foo = "bar" + func _ready(): + var id = get_instance_id() + var inst = instance_from_id(id) + print(inst.foo) # Prints bar + [/codeblock] + </description> + </method> + <method name="inverse_lerp"> + <return type="float"> + </return> + <argument index="0" name="from" type="float"> + </argument> + <argument index="1" name="to" type="float"> + </argument> + <argument index="2" name="weight" type="float"> + </argument> + <description> + Returns a normalized value considering the given range. This is the opposite of [method lerp]. + [codeblock] + var middle = lerp(20, 30, 0.75) + # `middle` is now 27.5. + # Now, we pretend to have forgotten the original ratio and want to get it back. + var ratio = inverse_lerp(20, 30, 27.5) + # `ratio` is now 0.75. + [/codeblock] + </description> + </method> + <method name="is_equal_approx"> + <return type="bool"> + </return> + <argument index="0" name="a" type="float"> + </argument> + <argument index="1" name="b" type="float"> + </argument> + <description> + Returns [code]true[/code] if [code]a[/code] and [code]b[/code] are approximately equal to each other. + Here, approximately equal means that [code]a[/code] and [code]b[/code] are within a small internal epsilon of each other, which scales with the magnitude of the numbers. + Infinity values of the same sign are considered equal. + </description> + </method> + <method name="is_inf"> + <return type="bool"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns whether [code]x[/code] is an infinity value (either positive infinity or negative infinity). + </description> + </method> + <method name="is_instance_id_valid"> + <return type="bool"> + </return> + <argument index="0" name="id" type="int"> + </argument> + <description> + </description> + </method> + <method name="is_instance_valid"> + <return type="bool"> + </return> + <argument index="0" name="instance" type="Variant"> + </argument> + <description> + Returns whether [code]instance[/code] is a valid object (e.g. has not been deleted from memory). + </description> + </method> + <method name="is_nan"> + <return type="bool"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns whether [code]x[/code] is a NaN ("Not a Number" or invalid) value. + </description> + </method> + <method name="is_zero_approx"> + <return type="bool"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns [code]true[/code] if [code]x[/code] is zero or almost zero. + This method is faster than using [method is_equal_approx] with one value as zero. + </description> + </method> + <method name="lerp"> + <return type="float"> + </return> + <argument index="0" name="from" type="float"> + </argument> + <argument index="1" name="to" type="float"> + </argument> + <argument index="2" name="weight" type="float"> + </argument> + <description> + Linearly interpolates between two values by a normalized value. This is the opposite of [method inverse_lerp]. + [codeblock] + lerp(0, 4, 0.75) # Returns 3.0 + [/codeblock] + </description> + </method> + <method name="lerp_angle"> + <return type="float"> + </return> + <argument index="0" name="from" type="float"> + </argument> + <argument index="1" name="to" type="float"> + </argument> + <argument index="2" name="weight" type="float"> + </argument> + <description> + Linearly interpolates between two angles (in radians) by a normalized value. + Similar to [method lerp], but interpolates correctly when the angles wrap around [constant @GDScript.TAU]. + [codeblock] + extends Sprite + var elapsed = 0.0 + func _process(delta): + var min_angle = deg2rad(0.0) + var max_angle = deg2rad(90.0) + rotation = lerp_angle(min_angle, max_angle, elapsed) + elapsed += delta + [/codeblock] + </description> + </method> + <method name="linear2db"> + <return type="float"> + </return> + <argument index="0" name="lin" type="float"> + </argument> + <description> + Converts from linear energy to decibels (audio). This can be used to implement volume sliders that behave as expected (since volume isn't linear). Example: + [codeblock] + # "Slider" refers to a node that inherits Range such as HSlider or VSlider. + # Its range must be configured to go from 0 to 1. + # Change the bus name if you'd like to change the volume of a specific bus only. + AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear2db($Slider.value)) + [/codeblock] + </description> + </method> + <method name="log"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Natural logarithm. The amount of time needed to reach a certain level of continuous growth. + [b]Note:[/b] This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. + [codeblock] + log(10) # Returns 2.302585 + [/codeblock] + [b]Note:[/b] The logarithm of [code]0[/code] returns [code]-inf[/code], while negative values return [code]-nan[/code]. + </description> + </method> + <method name="max" qualifiers="vararg"> + <return type="Variant"> + </return> + <description> + Returns the maximum of the given values. This method can take any number of arguments. + [codeblock] + max(1, 7, 3, -6, 5) # Returns 7 + [/codeblock] + </description> + </method> + <method name="maxf"> + <return type="float"> + </return> + <argument index="0" name="a" type="float"> + </argument> + <argument index="1" name="b" type="float"> + </argument> + <description> + Returns the maximum of two float values. + [codeblock] + maxf(3.6, 24) # Returns 24.0 + maxf(-3.99, -4) # Returns -3.99 + [/codeblock] + </description> + </method> + <method name="maxi"> + <return type="int"> + </return> + <argument index="0" name="a" type="int"> + </argument> + <argument index="1" name="b" type="int"> + </argument> + <description> + Returns the maximum of two int values. + [codeblock] + maxi(1, 2) # Returns 2 + maxi(-3, -4) # Returns -3 + [/codeblock] + </description> + </method> + <method name="min" qualifiers="vararg"> + <return type="Variant"> + </return> + <description> + Returns the minimum of the given values. This method can take any number of arguments. + [codeblock] + min(1, 7, 3, -6, 5) # Returns -6 + [/codeblock] + </description> + </method> + <method name="minf"> + <return type="float"> + </return> + <argument index="0" name="a" type="float"> + </argument> + <argument index="1" name="b" type="float"> + </argument> + <description> + Returns the minimum of two float values. + [codeblock] + minf(3.6, 24) # Returns 3.6 + minf(-3.99, -4) # Returns -4.0 + [/codeblock] + </description> + </method> + <method name="mini"> + <return type="int"> + </return> + <argument index="0" name="a" type="int"> + </argument> + <argument index="1" name="b" type="int"> + </argument> + <description> + Returns the minimum of two int values. + [codeblock] + mini(1, 2) # Returns 1 + mini(-3, -4) # Returns -4 + [/codeblock] + </description> + </method> + <method name="move_toward"> + <return type="float"> + </return> + <argument index="0" name="from" type="float"> + </argument> + <argument index="1" name="to" type="float"> + </argument> + <argument index="2" name="delta" type="float"> + </argument> + <description> + Moves [code]from[/code] toward [code]to[/code] by the [code]delta[/code] value. + Use a negative [code]delta[/code] value to move away. + [codeblock] + move_toward(5, 10, 4) # Returns 9 + move_toward(10, 5, 4) # Returns 6 + move_toward(10, 5, -1.5) # Returns 11.5 + [/codeblock] + </description> + </method> + <method name="nearest_po2"> + <return type="int"> + </return> + <argument index="0" name="value" type="int"> + </argument> + <description> + Returns the nearest equal or larger power of 2 for integer [code]value[/code]. + In other words, returns the smallest value [code]a[/code] where [code]a = pow(2, n)[/code] such that [code]value <= a[/code] for some non-negative integer [code]n[/code]. + [codeblock] + nearest_po2(3) # Returns 4 + nearest_po2(4) # Returns 4 + nearest_po2(5) # Returns 8 + + nearest_po2(0) # Returns 0 (this may not be what you expect) + nearest_po2(-1) # Returns 0 (this may not be what you expect) + [/codeblock] + [b]WARNING:[/b] Due to the way it is implemented, this function returns [code]0[/code] rather than [code]1[/code] for non-positive values of [code]value[/code] (in reality, 1 is the smallest integer power of 2). + </description> + </method> + <method name="polar2cartesian"> + <return type="Vector2"> + </return> + <argument index="0" name="r" type="float"> + </argument> + <argument index="1" name="th" type="float"> + </argument> + <description> + Converts a 2D point expressed in the polar coordinate system (a distance from the origin [code]r[/code] and an angle [code]th[/code]) to the cartesian coordinate system (X and Y axis). + </description> + </method> + <method name="pow"> + <return type="float"> + </return> + <argument index="0" name="base" type="float"> + </argument> + <argument index="1" name="exp" type="float"> + </argument> + <description> + Returns the result of [code]base[/code] raised to the power of [code]exp[/code]. + [codeblock] + pow(2, 5) # Returns 32 + [/codeblock] + </description> + </method> + <method name="print" qualifiers="vararg"> + <description> + Converts one or more arguments to strings in the best way possible and prints them to the console. + [codeblock] + a = [1, 2, 3] + print("a", "b", a) # Prints ab[1, 2, 3] + [/codeblock] + [b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. + </description> + </method> + <method name="printerr" qualifiers="vararg"> + <description> + Prints one or more arguments to strings in the best way possible to standard error line. + [codeblock] + printerr("prints to stderr") + [/codeblock] + </description> + </method> + <method name="printraw" qualifiers="vararg"> + <description> + Prints one or more arguments to strings in the best way possible to console. No newline is added at the end. + [codeblock] + printraw("A") + printraw("B") + # Prints AB + [/codeblock] + [b]Note:[/b] Due to limitations with Godot's built-in console, this only prints to the terminal. If you need to print in the editor, use another method, such as [method print]. + </description> + </method> + <method name="prints" qualifiers="vararg"> + <description> + Prints one or more arguments to the console with a space between each argument. + [codeblock] + prints("A", "B", "C") # Prints A B C + [/codeblock] + </description> + </method> + <method name="printt" qualifiers="vararg"> + <description> + Prints one or more arguments to the console with a tab between each argument. + [codeblock] + printt("A", "B", "C") # Prints A B C + [/codeblock] + </description> + </method> + <method name="push_error" qualifiers="vararg"> + <description> + Pushes an error message to Godot's built-in debugger and to the OS terminal. + [codeblock] + push_error("test error") # Prints "test error" to debugger and terminal as error call + [/codeblock] + [b]Note:[/b] Errors printed this way will not pause project execution. To print an error message and pause project execution in debug builds, use [code]assert(false, "test error")[/code] instead. + </description> + </method> + <method name="push_warning" qualifiers="vararg"> + <description> + Pushes a warning message to Godot's built-in debugger and to the OS terminal. + [codeblock] + push_warning("test warning") # Prints "test warning" to debugger and terminal as warning call + [/codeblock] + </description> + </method> + <method name="rad2deg"> + <return type="float"> + </return> + <argument index="0" name="rad" type="float"> + </argument> + <description> + Converts an angle expressed in radians to degrees. + [codeblock] + rad2deg(0.523599) # Returns 30 + [/codeblock] + </description> + </method> + <method name="rand_from_seed"> + <return type="PackedInt64Array"> + </return> + <argument index="0" name="seed" type="int"> + </argument> + <description> + Random from seed: pass a [code]seed[/code], and an array with both number and new seed is returned. "Seed" here refers to the internal state of the pseudo random number generator. The internal state of the current implementation is 64 bits. + </description> + </method> + <method name="randf"> + <return type="float"> + </return> + <description> + Returns a random floating point value on the interval [code][0, 1][/code]. + [codeblock] + randf() # Returns e.g. 0.375671 + [/codeblock] + </description> + </method> + <method name="randf_range"> + <return type="float"> + </return> + <argument index="0" name="from" type="float"> + </argument> + <argument index="1" name="to" type="float"> + </argument> + <description> + Random range, any floating point value between [code]from[/code] and [code]to[/code]. + [codeblock] + prints(randf_range(-10, 10), randf_range(-10, 10)) # Prints e.g. -3.844535 7.45315 + [/codeblock] + </description> + </method> + <method name="randi"> + <return type="int"> + </return> + <description> + Returns a random unsigned 32 bit integer. Use remainder to obtain a random value in the interval [code][0, N - 1][/code] (where N is smaller than 2^32). + [codeblock] + randi() # Returns random integer between 0 and 2^32 - 1 + randi() % 20 # Returns random integer between 0 and 19 + randi() % 100 # Returns random integer between 0 and 99 + randi() % 100 + 1 # Returns random integer between 1 and 100 + [/codeblock] + </description> + </method> + <method name="randi_range"> + <return type="int"> + </return> + <argument index="0" name="from" type="int"> + </argument> + <argument index="1" name="to" type="int"> + </argument> + <description> + Random range, any 32-bit integer value between [code]from[/code] and [code]to[/code] (inclusive). If [code]to[/code] is lesser than [code]from[/code] they are swapped. + [codeblock] + print(randi_range(0, 1)) # Prints 0 or 1 + print(randi_range(-10, 1000)) # Prints any number from -10 to 1000 + [/codeblock] + </description> + </method> + <method name="randomize"> + <description> + Randomizes the seed (or the internal state) of the random number generator. Current implementation reseeds using a number based on time. + [codeblock] + func _ready(): + randomize() + [/codeblock] + </description> + </method> + <method name="range_lerp"> + <return type="float"> + </return> + <argument index="0" name="value" type="float"> + </argument> + <argument index="1" name="istart" type="float"> + </argument> + <argument index="2" name="istop" type="float"> + </argument> + <argument index="3" name="ostart" type="float"> + </argument> + <argument index="4" name="ostop" type="float"> + </argument> + <description> + Maps a [code]value[/code] from range [code][istart, istop][/code] to [code][ostart, ostop][/code]. + [codeblock] + range_lerp(75, 0, 100, -1, 1) # Returns 0.5 + [/codeblock] + </description> + </method> + <method name="range_step_decimals"> + <return type="int"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + </description> + </method> + <method name="round"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Rounds [code]x[/code] to the nearest whole number, with halfway cases rounded away from zero. + [codeblock] + round(2.6) # Returns 3 + [/codeblock] + See also [method floor], [method ceil], and [method stepify]. + </description> + </method> + <method name="seed"> + <argument index="0" name="base" type="int"> + </argument> + <description> + Sets seed for the random number generator. + [codeblock] + my_seed = "Godot Rocks" + seed(my_seed.hash()) + [/codeblock] + </description> + </method> + <method name="sign"> + <return type="Variant"> + </return> + <argument index="0" name="x" type="Variant"> + </argument> + <description> + </description> + </method> + <method name="signf"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the sign of [code]x[/code] as a float: -1.0 or 1.0. Returns 0.0 if [code]x[/code] is 0. + [codeblock] + sign(-6.0) # Returns -1.0 + sign(0.0) # Returns 0.0 + sign(6.0) # Returns 1.0 + [/codeblock] + </description> + </method> + <method name="signi"> + <return type="int"> + </return> + <argument index="0" name="x" type="int"> + </argument> + <description> + Returns the sign of [code]x[/code] as an integer: -1 or 1. Returns 0 if [code]x[/code] is 0. + [codeblock] + sign(-6) # Returns -1 + sign(0) # Returns 0 + sign(6) # Returns 1 + [/codeblock] + </description> + </method> + <method name="sin"> + <return type="float"> + </return> + <argument index="0" name="angle_rad" type="float"> + </argument> + <description> + Returns the sine of angle [code]angle_rad[/code] in radians. + [codeblock] + sin(0.523599) # Returns 0.5 + [/codeblock] + </description> + </method> + <method name="sinh"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the hyperbolic sine of [code]x[/code]. + [codeblock] + a = log(2.0) # Returns 0.693147 + sinh(a) # Returns 0.75 + [/codeblock] + </description> + </method> + <method name="smoothstep"> + <return type="float"> + </return> + <argument index="0" name="from" type="float"> + </argument> + <argument index="1" name="to" type="float"> + </argument> + <argument index="2" name="x" type="float"> + </argument> + <description> + Returns the result of smoothly interpolating the value of [code]x[/code] between [code]0[/code] and [code]1[/code], based on the where [code]x[/code] lies with respect to the edges [code]from[/code] and [code]to[/code]. + The return value is [code]0[/code] if [code]x <= from[/code], and [code]1[/code] if [code]x >= to[/code]. If [code]x[/code] lies between [code]from[/code] and [code]to[/code], the returned value follows an S-shaped curve that maps [code]x[/code] between [code]0[/code] and [code]1[/code]. + This S-shaped curve is the cubic Hermite interpolator, given by [code]f(x) = 3*x^2 - 2*x^3[/code]. + [codeblock] + smoothstep(0, 2, -5.0) # Returns 0.0 + smoothstep(0, 2, 0.5) # Returns 0.15625 + smoothstep(0, 2, 1.0) # Returns 0.5 + smoothstep(0, 2, 2.0) # Returns 1.0 + [/codeblock] + </description> + </method> + <method name="sqrt"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the square root of [code]x[/code], where [code]x[/code] is a non-negative number. + [codeblock] + sqrt(9) # Returns 3 + [/codeblock] + [b]Note:[/b]Negative values of [code]x[/code] return NaN. If you need negative inputs, use [code]System.Numerics.Complex[/code] in C#. + </description> + </method> + <method name="step_decimals"> + <return type="int"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the position of the first non-zero digit, after the decimal point. Note that the maximum return value is 10, which is a design decision in the implementation. + [codeblock] + # n is 0 + n = step_decimals(5) + # n is 4 + n = step_decimals(1.0005) + # n is 9 + n = step_decimals(0.000000005) + [/codeblock] + </description> + </method> + <method name="stepify"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <argument index="1" name="step" type="float"> + </argument> + <description> + Snaps float value [code]x[/code] to a given [code]step[/code]. This can also be used to round a floating point number to an arbitrary number of decimals. + [codeblock] + stepify(100, 32) # Returns 96 + stepify(3.14159, 0.01) # Returns 3.14 + [/codeblock] + See also [method ceil], [method floor], and [method round]. + </description> + </method> + <method name="str" qualifiers="vararg"> + <return type="String"> + </return> + <description> + Converts one or more arguments to string in the best way possible. + </description> + </method> + <method name="str2var"> + <return type="Variant"> + </return> + <argument index="0" name="string" type="String"> + </argument> + <description> + Converts a formatted string that was returned by [method var2str] to the original value. + [codeblock] + a = '{ "a": 1, "b": 2 }' + b = str2var(a) + print(b["a"]) # Prints 1 + [/codeblock] + </description> + </method> + <method name="tan"> + <return type="float"> + </return> + <argument index="0" name="angle_rad" type="float"> + </argument> + <description> + Returns the tangent of angle [code]angle_rad[/code] in radians. + [codeblock] + tan(deg2rad(45)) # Returns 1 + [/codeblock] + </description> + </method> + <method name="tanh"> + <return type="float"> + </return> + <argument index="0" name="x" type="float"> + </argument> + <description> + Returns the hyperbolic tangent of [code]x[/code]. + [codeblock] + a = log(2.0) # Returns 0.693147 + tanh(a) # Returns 0.6 + [/codeblock] + </description> + </method> + <method name="typeof"> + <return type="int"> + </return> + <argument index="0" name="variable" type="Variant"> + </argument> + <description> + Returns the internal type of the given Variant object, using the [enum Variant.Type] values. + [codeblock] + p = parse_json('["a", "b", "c"]') + if typeof(p) == TYPE_ARRAY: + print(p[0]) # Prints a + else: + print("unexpected results") + [/codeblock] + </description> + </method> + <method name="var2bytes"> + <return type="PackedByteArray"> + </return> + <argument index="0" name="variable" type="Variant"> + </argument> + <description> + Encodes a [Variant] value to a byte array, without encoding objects. Deserialization can be done with [method bytes2var]. + [b]Note:[/b] If you need object serialization, see [method var2bytes_with_objects]. + </description> + </method> + <method name="var2bytes_with_objects"> + <return type="PackedByteArray"> + </return> + <argument index="0" name="variable" type="Variant"> + </argument> + <description> + Encodes a [Variant] value to a byte array. Encoding objects is allowed (and can potentially include code). Deserialization can be done with [method bytes2var_with_objects]. + </description> + </method> + <method name="var2str"> + <return type="String"> + </return> + <argument index="0" name="variable" type="Variant"> + </argument> + <description> + Converts a Variant [code]variable[/code] to a formatted string that can later be parsed using [method str2var]. + [codeblock] + a = { "a": 1, "b": 2 } + print(var2str(a)) + [/codeblock] + prints + [codeblock] + { + "a": 1, + "b": 2 + } + [/codeblock] + </description> + </method> + <method name="weakref"> + <return type="Variant"> + </return> + <argument index="0" name="obj" type="Variant"> + </argument> + <description> + Returns a weak reference to an object, or [code]null[/code] is the argument is invalid. + A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it. + </description> + </method> + <method name="wrapf"> + <return type="float"> + </return> + <argument index="0" name="value" type="float"> + </argument> + <argument index="1" name="min" type="float"> + </argument> + <argument index="2" name="max" type="float"> + </argument> + <description> + Wraps float [code]value[/code] between [code]min[/code] and [code]max[/code]. + Usable for creating loop-alike behavior or infinite surfaces. + [codeblock] + # Infinite loop between 5.0 and 9.9 + value = wrapf(value + 0.1, 5.0, 10.0) + [/codeblock] + [codeblock] + # Infinite rotation (in radians) + angle = wrapf(angle + 0.1, 0.0, TAU) + [/codeblock] + [codeblock] + # Infinite rotation (in radians) + angle = wrapf(angle + 0.1, -PI, PI) + [/codeblock] + [b]Note:[/b] If [code]min[/code] is [code]0[/code], this is equivalent to [method fposmod], so prefer using that instead. + [code]wrapf[/code] is more flexible than using the [method fposmod] approach by giving the user control over the minimum value. + </description> + </method> + <method name="wrapi"> + <return type="int"> + </return> + <argument index="0" name="value" type="int"> + </argument> + <argument index="1" name="min" type="int"> + </argument> + <argument index="2" name="max" type="int"> + </argument> + <description> + Wraps integer [code]value[/code] between [code]min[/code] and [code]max[/code]. + Usable for creating loop-alike behavior or infinite surfaces. + [codeblock] + # Infinite loop between 5 and 9 + frame = wrapi(frame + 1, 5, 10) + [/codeblock] + [codeblock] + # result is -2 + var result = wrapi(-6, -5, -1) + [/codeblock] + </description> + </method> </methods> <members> <member name="AudioServer" type="AudioServer" setter="" getter=""> @@ -952,130 +2093,61 @@ <constant name="BUTTON_MASK_XBUTTON2" value="256" enum="ButtonList"> Extra mouse button 2 mask. </constant> - <constant name="JOY_INVALID_BUTTON" value="-1" enum="JoyButtonList"> + <constant name="JOY_BUTTON_INVALID" value="-1" enum="JoyButtonList"> An invalid game controller button. </constant> <constant name="JOY_BUTTON_A" value="0" enum="JoyButtonList"> - Game controller SDL button A. + Game controller SDL button A. Corresponds to the bottom action button: Sony Cross, Xbox A, Nintendo B. </constant> <constant name="JOY_BUTTON_B" value="1" enum="JoyButtonList"> - Game controller SDL button B. + Game controller SDL button B. Corresponds to the right action button: Sony Circle, Xbox B, Nintendo A. </constant> <constant name="JOY_BUTTON_X" value="2" enum="JoyButtonList"> - Game controller SDL button X. + Game controller SDL button X. Corresponds to the left action button: Sony Square, Xbox X, Nintendo Y. </constant> <constant name="JOY_BUTTON_Y" value="3" enum="JoyButtonList"> - Game controller SDL button Y. + Game controller SDL button Y. Corresponds to the top action button: Sony Triangle, Xbox Y, Nintendo X. </constant> <constant name="JOY_BUTTON_BACK" value="4" enum="JoyButtonList"> - Game controller SDL back button. + Game controller SDL back button. Corresponds to the Sony Select, Xbox Back, Nintendo - button. </constant> <constant name="JOY_BUTTON_GUIDE" value="5" enum="JoyButtonList"> - Game controller SDL guide button. + Game controller SDL guide button. Corresponds to the Sony PS, Xbox Home button. </constant> <constant name="JOY_BUTTON_START" value="6" enum="JoyButtonList"> - Game controller SDL start button. + Game controller SDL start button. Corresponds to the Nintendo + button. </constant> <constant name="JOY_BUTTON_LEFT_STICK" value="7" enum="JoyButtonList"> - Game controller SDL left stick button. + Game controller SDL left stick button. Corresponds to the Sony L3, Xbox L/LS button. </constant> <constant name="JOY_BUTTON_RIGHT_STICK" value="8" enum="JoyButtonList"> - Game controller SDL right stick button. + Game controller SDL right stick button. Corresponds to the Sony R3, Xbox R/RS button. </constant> <constant name="JOY_BUTTON_LEFT_SHOULDER" value="9" enum="JoyButtonList"> - Game controller SDL left shoulder button. + Game controller SDL left shoulder button. Corresponds to the Sony L1, Xbox LB button. </constant> <constant name="JOY_BUTTON_RIGHT_SHOULDER" value="10" enum="JoyButtonList"> - Game controller SDL right shoulder button. + Game controller SDL right shoulder button. Corresponds to the Sony R1, Xbox RB button. </constant> <constant name="JOY_BUTTON_DPAD_UP" value="11" enum="JoyButtonList"> - Game controller SDL D-pad up button. + Game controller D-pad up button. </constant> <constant name="JOY_BUTTON_DPAD_DOWN" value="12" enum="JoyButtonList"> - Game controller SDL D-pad down button. + Game controller D-pad down button. </constant> <constant name="JOY_BUTTON_DPAD_LEFT" value="13" enum="JoyButtonList"> - Game controller SDL D-pad left button. + Game controller D-pad left button. </constant> <constant name="JOY_BUTTON_DPAD_RIGHT" value="14" enum="JoyButtonList"> - Game controller SDL D-pad right button. + Game controller D-pad right button. </constant> - <constant name="JOY_SDL_BUTTONS" value="15" enum="JoyButtonList"> + <constant name="JOY_BUTTON_SDL_MAX" value="15" enum="JoyButtonList"> The number of SDL game controller buttons. </constant> - <constant name="JOY_SONY_X" value="0" enum="JoyButtonList"> - Sony DualShock controller X button maps to SDL button A. - </constant> - <constant name="JOY_SONY_CROSS" value="0" enum="JoyButtonList"> - Sony DualShock controller cross button maps to SDL button A. - </constant> - <constant name="JOY_SONY_CIRCLE" value="1" enum="JoyButtonList"> - Sony DualShock controller circle button maps to SDL button B. - </constant> - <constant name="JOY_SONY_SQUARE" value="2" enum="JoyButtonList"> - Sony DualShock controller square button maps to SDL button X. - </constant> - <constant name="JOY_SONY_TRIANGLE" value="3" enum="JoyButtonList"> - Sony DualShock controller triangle button maps to SDL button Y. - </constant> - <constant name="JOY_SONY_SELECT" value="4" enum="JoyButtonList"> - Sony DualShock controller select button maps to SDL back button. - </constant> - <constant name="JOY_SONY_START" value="6" enum="JoyButtonList"> - Sony DualShock controller start button maps to SDL start button. - </constant> - <constant name="JOY_SONY_PS" value="5" enum="JoyButtonList"> - Sony DualShock controller PS button maps to SDL guide button. - </constant> - <constant name="JOY_SONY_L1" value="9" enum="JoyButtonList"> - Sony DualShock controller L1 button maps to SDL left shoulder button. - </constant> - <constant name="JOY_SONY_R1" value="10" enum="JoyButtonList"> - Sony DualShock controller R1 button maps to SDL right shoulder button. - </constant> - <constant name="JOY_SONY_L3" value="7" enum="JoyButtonList"> - Sony DualShock controller L3 button maps to SDL left stick button. - </constant> - <constant name="JOY_SONY_R3" value="8" enum="JoyButtonList"> - Sony DualShock controller R3 button maps to SDL right stick button. - </constant> - <constant name="JOY_XBOX_A" value="0" enum="JoyButtonList"> - Xbox game controller A button maps to SDL button A. - </constant> - <constant name="JOY_XBOX_B" value="1" enum="JoyButtonList"> - Xbox game controller B button maps to SDL button B. - </constant> - <constant name="JOY_XBOX_X" value="2" enum="JoyButtonList"> - Xbox game controller X button maps to SDL button X. - </constant> - <constant name="JOY_XBOX_Y" value="3" enum="JoyButtonList"> - Xbox game controller Y button maps to SDL button Y. - </constant> - <constant name="JOY_XBOX_BACK" value="4" enum="JoyButtonList"> - Xbox game controller back button maps to SDL back button. - </constant> - <constant name="JOY_XBOX_START" value="6" enum="JoyButtonList"> - Xbox game controller start button maps to SDL start button. - </constant> - <constant name="JOY_XBOX_HOME" value="5" enum="JoyButtonList"> - Xbox game controller home button maps to SDL guide button. - </constant> - <constant name="JOY_XBOX_LS" value="7" enum="JoyButtonList"> - Xbox game controller left stick button maps to SDL left stick button. - </constant> - <constant name="JOY_XBOX_RS" value="8" enum="JoyButtonList"> - Xbox game controller right stick button maps to SDL right stick button. - </constant> - <constant name="JOY_XBOX_LB" value="9" enum="JoyButtonList"> - Xbox game controller left bumper button maps to SDL left shoulder button. - </constant> - <constant name="JOY_XBOX_RB" value="10" enum="JoyButtonList"> - Xbox game controller right bumper button maps to SDL right shoulder button. - </constant> <constant name="JOY_BUTTON_MAX" value="36" enum="JoyButtonList"> - The maximum number of game controller buttons. + The maximum number of game controller buttons: Android supports up to 36 buttons. </constant> - <constant name="JOY_INVALID_AXIS" value="-1" enum="JoyAxisList"> + <constant name="JOY_AXIS_INVALID" value="-1" enum="JoyAxisList"> An invalid game controller axis. </constant> <constant name="JOY_AXIS_LEFT_X" value="0" enum="JoyAxisList"> @@ -1096,41 +2168,11 @@ <constant name="JOY_AXIS_TRIGGER_RIGHT" value="5" enum="JoyAxisList"> Game controller right trigger axis. </constant> - <constant name="JOY_SDL_AXES" value="6" enum="JoyAxisList"> + <constant name="JOY_AXIS_SDL_MAX" value="6" enum="JoyAxisList"> The number of SDL game controller axes. </constant> - <constant name="JOY_AXIS_0_X" value="0" enum="JoyAxisList"> - Game controller joystick 0 x-axis. - </constant> - <constant name="JOY_AXIS_0_Y" value="1" enum="JoyAxisList"> - Game controller joystick 0 y-axis. - </constant> - <constant name="JOY_AXIS_1_X" value="2" enum="JoyAxisList"> - Game controller joystick 1 x-axis. - </constant> - <constant name="JOY_AXIS_1_Y" value="3" enum="JoyAxisList"> - Game controller joystick 1 y-axis. - </constant> - <constant name="JOY_AXIS_2_X" value="4" enum="JoyAxisList"> - Game controller joystick 2 x-axis. - </constant> - <constant name="JOY_AXIS_2_Y" value="5" enum="JoyAxisList"> - Game controller joystick 2 y-axis. - </constant> - <constant name="JOY_AXIS_3_X" value="6" enum="JoyAxisList"> - Game controller joystick 3 x-axis. - </constant> - <constant name="JOY_AXIS_3_Y" value="7" enum="JoyAxisList"> - Game controller joystick 3 y-axis. - </constant> - <constant name="JOY_AXIS_4_X" value="8" enum="JoyAxisList"> - Game controller joystick 4 x-axis. - </constant> - <constant name="JOY_AXIS_4_Y" value="9" enum="JoyAxisList"> - Game controller joystick 4 y-axis. - </constant> <constant name="JOY_AXIS_MAX" value="10" enum="JoyAxisList"> - The maximum number of game controller axes. + The maximum number of game controller axes: OpenVR supports up to 5 Joysticks making a total of 10 axes. </constant> <constant name="MIDI_MESSAGE_NOTE_OFF" value="8" enum="MidiMessageList"> MIDI note OFF message. diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 0ad5960d4a..6a9eb89602 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -38,8 +38,9 @@ GD.Print(array1 + array2); // Prints [One, 2, 3, Four] [/csharp] [/codeblocks] - Note that concatenating with [code]+=[/code] operator will create a new array. If you want to append another array to an existing array, [method append_array] is more efficient. + [b]Note:[/b] Concatenating with the [code]+=[/code] operator will create a new array, which has a cost. If you want to append another array to an existing array, [method append_array] is more efficient. [b]Note:[/b] Arrays are always passed by reference. To get a copy of an array which can be modified independently of the original array, use [method duplicate]. + [b]Note:[/b] When declaring an array with [code]const[/code], the array itself can still be mutated by defining the values at individual indices or pushing/removing elements. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized. </description> <tutorials> </tutorials> diff --git a/doc/classes/AspectRatioContainer.xml b/doc/classes/AspectRatioContainer.xml new file mode 100644 index 0000000000..7b41133139 --- /dev/null +++ b/doc/classes/AspectRatioContainer.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="AspectRatioContainer" inherits="Container" version="4.0"> + <brief_description> + Container that preserves its child controls' aspect ratio. + </brief_description> + <description> + Arranges child controls in a way to preserve their aspect ratio automatically whenever the container is resized. Solves the problem where the container size is dynamic and the contents' size needs to adjust accordingly without losing proportions. + </description> + <tutorials> + </tutorials> + <methods> + </methods> + <members> + <member name="alignment_horizontal" type="int" setter="set_alignment_horizontal" getter="get_alignment_horizontal" enum="AspectRatioContainer.AlignMode" default="1"> + Specifies the horizontal relative position of child controls. + </member> + <member name="alignment_vertical" type="int" setter="set_alignment_vertical" getter="get_alignment_vertical" enum="AspectRatioContainer.AlignMode" default="1"> + Specifies the vertical relative position of child controls. + </member> + <member name="ratio" type="float" setter="set_ratio" getter="get_ratio" default="1.0"> + The aspect ratio to enforce on child controls. This is the width divided by the height. The ratio depends on the [member stretch_mode]. + </member> + <member name="stretch_mode" type="int" setter="set_stretch_mode" getter="get_stretch_mode" enum="AspectRatioContainer.StretchMode" default="2"> + The stretch mode used to align child controls. + </member> + </members> + <constants> + <constant name="STRETCH_WIDTH_CONTROLS_HEIGHT" value="0" enum="StretchMode"> + The height of child controls is automatically adjusted based on the width of the container. + </constant> + <constant name="STRETCH_HEIGHT_CONTROLS_WIDTH" value="1" enum="StretchMode"> + The width of child controls is automatically adjusted based on the height of the container. + </constant> + <constant name="STRETCH_FIT" value="2" enum="StretchMode"> + The bounding rectangle of child controls is automatically adjusted to fit inside the container while keeping the aspect ratio. + </constant> + <constant name="STRETCH_COVER" value="3" enum="StretchMode"> + The width and height of child controls is automatically adjusted to make their bounding rectangle cover the entire area of the container while keeping the aspect ratio. + When the bounding rectangle of child controls exceed the container's size and [member Control.rect_clip_content] is enabled, this allows to show only the container's area restricted by its own bounding rectangle. + </constant> + <constant name="ALIGN_BEGIN" value="0" enum="AlignMode"> + Aligns child controls with the beginning (left or top) of the container. + </constant> + <constant name="ALIGN_CENTER" value="1" enum="AlignMode"> + Aligns child controls with the center of the container. + </constant> + <constant name="ALIGN_END" value="2" enum="AlignMode"> + Aligns child controls with the end (right or bottom) of the container. + </constant> + </constants> +</class> diff --git a/doc/classes/AudioStreamPlayer3D.xml b/doc/classes/AudioStreamPlayer3D.xml index aadbc865bb..7a8c4b2cc7 100644 --- a/doc/classes/AudioStreamPlayer3D.xml +++ b/doc/classes/AudioStreamPlayer3D.xml @@ -4,7 +4,7 @@ Plays 3D sound in 3D space. </brief_description> <description> - Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space. + Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space. For greater realism, a low-pass filter is automatically applied to distant sounds. This can be disabled by setting [member attenuation_filter_cutoff_hz] to [code]20500[/code]. By default, audio is heard from the camera position. This can be changed by adding a [Listener3D] node to the scene and enabling it by calling [method Listener3D.make_current] on it. </description> <tutorials> @@ -56,19 +56,19 @@ Areas in which this sound plays. </member> <member name="attenuation_filter_cutoff_hz" type="float" setter="set_attenuation_filter_cutoff_hz" getter="get_attenuation_filter_cutoff_hz" default="5000.0"> - Dampens audio above this frequency, in Hz. + Dampens audio using a low-pass filter above this frequency, in Hz. To disable the dampening effect entirely, set this to [code]20500[/code] as this frequency is above the human hearing limit. </member> <member name="attenuation_filter_db" type="float" setter="set_attenuation_filter_db" getter="get_attenuation_filter_db" default="-24.0"> - Amount how much the filter affects the loudness, in dB. + Amount how much the filter affects the loudness, in decibels. </member> <member name="attenuation_model" type="int" setter="set_attenuation_model" getter="get_attenuation_model" enum="AudioStreamPlayer3D.AttenuationModel" default="0"> Decides if audio should get quieter with distance linearly, quadratically, logarithmically, or not be affected by distance, effectively disabling attenuation. </member> <member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled" default="false"> - If [code]true[/code], audio plays when added to scene tree. + If [code]true[/code], audio plays when the AudioStreamPlayer3D node is added to scene tree. </member> <member name="bus" type="StringName" setter="set_bus" getter="get_bus" default="@"Master""> - Bus on which this audio is playing. + The bus on which this audio is playing. </member> <member name="doppler_tracking" type="int" setter="set_doppler_tracking" getter="get_doppler_tracking" enum="AudioStreamPlayer3D.DopplerTracking" default="0"> Decides in which step the Doppler effect should be calculated. @@ -80,10 +80,10 @@ If [code]true[/code], the audio should be dampened according to the direction of the sound. </member> <member name="emission_angle_filter_attenuation_db" type="float" setter="set_emission_angle_filter_attenuation_db" getter="get_emission_angle_filter_attenuation_db" default="-12.0"> - Dampens audio if camera is outside of [member emission_angle_degrees] and [member emission_angle_enabled] is set by this factor, in dB. + Dampens audio if camera is outside of [member emission_angle_degrees] and [member emission_angle_enabled] is set by this factor, in decibels. </member> <member name="max_db" type="float" setter="set_max_db" getter="get_max_db" default="3.0"> - Sets the absolute maximum of the soundlevel, in dB. + Sets the absolute maximum of the soundlevel, in decibels. </member> <member name="max_distance" type="float" setter="set_max_distance" getter="get_max_distance" default="0.0"> Sets the distance from which the [member out_of_range_mode] takes effect. Has no effect if set to 0. @@ -98,16 +98,16 @@ If [code]true[/code], audio is playing. </member> <member name="stream" type="AudioStream" setter="set_stream" getter="get_stream"> - The [AudioStream] object to be played. + The [AudioStream] resource to be played. </member> <member name="stream_paused" type="bool" setter="set_stream_paused" getter="get_stream_paused" default="false"> - If [code]true[/code], the playback is paused. You can resume it by setting [code]stream_paused[/code] to [code]false[/code]. + If [code]true[/code], the playback is paused. You can resume it by setting [member stream_paused] to [code]false[/code]. </member> <member name="unit_db" type="float" setter="set_unit_db" getter="get_unit_db" default="0.0"> - Base sound level unaffected by dampening, in dB. + The base sound level unaffected by dampening, in decibels. </member> <member name="unit_size" type="float" setter="set_unit_size" getter="get_unit_size" default="1.0"> - Factor for the attenuation effect. + The factor for the attenuation effect. Higher values make the sound audible over a larger distance. </member> </members> <signals> @@ -128,13 +128,13 @@ Logarithmic dampening of loudness according to distance. </constant> <constant name="ATTENUATION_DISABLED" value="3" enum="AttenuationModel"> - No dampening of loudness according to distance. + No dampening of loudness according to distance. The sound will still be heard positionally, unlike an [AudioStreamPlayer]. </constant> <constant name="OUT_OF_RANGE_MIX" value="0" enum="OutOfRangeMode"> - Mix this audio in, even when it's out of range. + Mix this audio in, even when it's out of range. This increases CPU usage, but keeps the sound playing at the correct position if the camera leaves and enters the [AudioStreamPlayer3D]'s [member max_distance] radius. </constant> <constant name="OUT_OF_RANGE_PAUSE" value="1" enum="OutOfRangeMode"> - Pause this audio when it gets out of range. + Pause this audio when it gets out of range. This decreases CPU usage, but will cause the sound to restart if the camera leaves and enters the [AudioStreamPlayer3D]'s [member max_distance] radius. </constant> <constant name="DOPPLER_TRACKING_DISABLED" value="0" enum="DopplerTracking"> Disables doppler tracking. diff --git a/doc/classes/Color.xml b/doc/classes/Color.xml index ae8703c837..9705a196ed 100644 --- a/doc/classes/Color.xml +++ b/doc/classes/Color.xml @@ -63,13 +63,13 @@ <argument index="3" name="a" type="float"> </argument> <description> - Constructs a [Color] from an RGBA profile using values between 0 and 1. + Constructs a [Color] from RGBA values, typically between 0 and 1. [codeblocks] [gdscript] - var color = Color(0.2, 1.0, 0.7, 0.8) # Equivalent to RGBA(51, 255, 178, 204) + var color = Color(0.2, 1.0, 0.7, 0.8) # Similar to `Color8(51, 255, 178, 204)` [/gdscript] [csharp] - var color = new Color(0.2f, 1.0f, 0.7f, 0.8f); // Equivalent to RGBA(51, 255, 178, 255, 204) + var color = new Color(0.2f, 1.0f, 0.7f, 0.8f); // Similar to `Color.Color8(51, 255, 178, 255, 204)` [/csharp] [/codeblocks] </description> @@ -84,13 +84,13 @@ <argument index="2" name="b" type="float"> </argument> <description> - Constructs a color from an RGB profile using values between 0 and 1. Alpha will always be 1. + Constructs a [Color] from RGB values, typically between 0 and 1. Alpha will be 1. [codeblocks] [gdscript] - var color = Color(0.2, 1.0, 0.7) # Equivalent to RGBA(51, 255, 178, 255) + var color = Color(0.2, 1.0, 0.7) # Similar to `Color8(51, 255, 178, 255)` [/gdscript] [csharp] - var color = new Color(0.2f, 1.0f, 0.7f); // Equivalent to RGBA(51, 255, 178, 255) + var color = new Color(0.2f, 1.0f, 0.7f); // Similar to `Color.Color8(51, 255, 178, 255)` [/csharp] [/codeblocks] </description> @@ -143,11 +143,11 @@ [codeblocks] [gdscript] var color = Color(0.3, 0.4, 0.9) - var inverted_color = color.inverted() # A color of an RGBA(178, 153, 26, 255) + var inverted_color = color.inverted() # Equivalent to `Color(0.7, 0.6, 0.1)` [/gdscript] [csharp] var color = new Color(0.3f, 0.4f, 0.9f); - Color invertedColor = color.Inverted(); // A color of an RGBA(178, 153, 26, 255) + Color invertedColor = color.Inverted(); // Equivalent to `new Color(0.7f, 0.6f, 0.1f)` [/csharp] [/codeblocks] </description> @@ -174,12 +174,12 @@ [gdscript] var c1 = Color(1.0, 0.0, 0.0) var c2 = Color(0.0, 1.0, 0.0) - var lerp_color = c1.lerp(c2, 0.5) # A color of an RGBA(128, 128, 0, 255) + var lerp_color = c1.lerp(c2, 0.5) # Equivalent to `Color(0.5, 0.5, 0.0)` [/gdscript] [csharp] var c1 = new Color(1.0f, 0.0f, 0.0f); var c2 = new Color(0.0f, 1.0f, 0.0f); - Color lerpColor = c1.Lerp(c2, 0.5f); // A color of an RGBA(128, 128, 0, 255) + Color lerpColor = c1.Lerp(c2, 0.5f); // Equivalent to `new Color(0.5f, 0.5f, 0.0f)` [/csharp] [/codeblocks] </description> @@ -299,7 +299,7 @@ <return type="int"> </return> <description> - Returns the color's 32-bit integer in ABGR format (each byte represents a component of the ABGR profile). ABGR is the reversed version of the default format. + Returns the color converted to a 32-bit integer in ABGR format (each byte represents a color channel). ABGR is the reversed version of the default format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -316,7 +316,7 @@ <return type="int"> </return> <description> - Returns the color's 64-bit integer in ABGR format (each word represents a component of the ABGR profile). ABGR is the reversed version of the default format. + Returns the color converted to a 64-bit integer in ABGR format (each word represents a color channel). ABGR is the reversed version of the default format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -333,7 +333,7 @@ <return type="int"> </return> <description> - Returns the color's 32-bit integer in ARGB format (each byte represents a component of the ARGB profile). ARGB is more compatible with DirectX. + Returns the color converted to a 32-bit integer in ARGB format (each byte represents a color channel). ARGB is more compatible with DirectX. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -350,7 +350,7 @@ <return type="int"> </return> <description> - Returns the color's 64-bit integer in ARGB format (each word represents a component of the ARGB profile). ARGB is more compatible with DirectX. + Returns the color converted to a 64-bit integer in ARGB format (each word represents a color channel). ARGB is more compatible with DirectX. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -369,7 +369,7 @@ <argument index="0" name="with_alpha" type="bool" default="true"> </argument> <description> - Returns the color's HTML hexadecimal color string in RGBA format (ex: [code]ff34f822[/code]). + Returns the color converted to an HTML hexadecimal color string in RGBA format (ex: [code]ff34f822[/code]). Setting [code]with_alpha[/code] to [code]false[/code] excludes alpha from the hexadecimal string (and uses RGB instead of RGBA format). [codeblocks] [gdscript] @@ -389,7 +389,7 @@ <return type="int"> </return> <description> - Returns the color's 32-bit integer in RGBA format (each byte represents a component of the RGBA profile). RGBA is Godot's default format. + Returns the color converted to a 32-bit integer in RGBA format (each byte represents a color channel). RGBA is Godot's default format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -406,7 +406,7 @@ <return type="int"> </return> <description> - Returns the color's 64-bit integer in RGBA format (each word represents a component of the RGBA profile). RGBA is Godot's default format. + Returns the color converted to a 64-bit integer in RGBA format (each word represents a color channel). RGBA is Godot's default format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 6ea7b79dff..eb0b941da5 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -446,7 +446,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns a color from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. + Returns a color from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]node_type[/code]. [codeblocks] [gdscript] func _ready(): @@ -469,7 +469,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns a constant from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. + Returns a constant from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]node_type[/code]. </description> </method> <method name="get_theme_font" qualifiers="const"> @@ -480,7 +480,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns a font from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. + Returns a font from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]node_type[/code]. </description> </method> <method name="get_theme_icon" qualifiers="const"> @@ -491,7 +491,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns an icon from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. + Returns an icon from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]node_type[/code]. </description> </method> <method name="get_theme_stylebox" qualifiers="const"> @@ -502,7 +502,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns a [StyleBox] from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. + Returns a [StyleBox] from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]node_type[/code]. </description> </method> <method name="get_tooltip" qualifiers="const"> @@ -566,7 +566,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns [code]true[/code] if [Color] with given [code]name[/code] and associated with [Control] of given [code]type[/code] exists in assigned [Theme]. + Returns [code]true[/code] if [Color] with given [code]name[/code] and associated with [Control] of given [code]node_type[/code] exists in assigned [Theme]. </description> </method> <method name="has_theme_color_override" qualifiers="const"> @@ -586,7 +586,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns [code]true[/code] if constant with given [code]name[/code] and associated with [Control] of given [code]type[/code] exists in assigned [Theme]. + Returns [code]true[/code] if constant with given [code]name[/code] and associated with [Control] of given [code]node_type[/code] exists in assigned [Theme]. </description> </method> <method name="has_theme_constant_override" qualifiers="const"> @@ -606,7 +606,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns [code]true[/code] if font with given [code]name[/code] and associated with [Control] of given [code]type[/code] exists in assigned [Theme]. + Returns [code]true[/code] if font with given [code]name[/code] and associated with [Control] of given [code]node_type[/code] exists in assigned [Theme]. </description> </method> <method name="has_theme_font_override" qualifiers="const"> @@ -626,7 +626,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns [code]true[/code] if icon with given [code]name[/code] and associated with [Control] of given [code]type[/code] exists in assigned [Theme]. + Returns [code]true[/code] if icon with given [code]name[/code] and associated with [Control] of given [code]node_type[/code] exists in assigned [Theme]. </description> </method> <method name="has_theme_icon_override" qualifiers="const"> @@ -655,7 +655,7 @@ <argument index="1" name="type" type="StringName" default=""""> </argument> <description> - Returns [code]true[/code] if [StyleBox] with given [code]name[/code] and associated with [Control] of given [code]type[/code] exists in assigned [Theme]. + Returns [code]true[/code] if [StyleBox] with given [code]name[/code] and associated with [Control] of given [code]node_type[/code] exists in assigned [Theme]. </description> </method> <method name="has_theme_stylebox_override" qualifiers="const"> diff --git a/doc/classes/Curve2D.xml b/doc/classes/Curve2D.xml index 8ac6258e97..2d50d98a74 100644 --- a/doc/classes/Curve2D.xml +++ b/doc/classes/Curve2D.xml @@ -80,7 +80,7 @@ <argument index="0" name="idx" type="int"> </argument> <description> - Returns the position of the control point leading to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0)[/code]. + Returns the position of the control point leading to the vertex [code]idx[/code]. The returned position is relative to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0)[/code]. </description> </method> <method name="get_point_out" qualifiers="const"> @@ -89,7 +89,7 @@ <argument index="0" name="idx" type="int"> </argument> <description> - Returns the position of the control point leading out of the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0)[/code]. + Returns the position of the control point leading out of the vertex [code]idx[/code]. The returned position is relative to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0)[/code]. </description> </method> <method name="get_point_position" qualifiers="const"> @@ -152,7 +152,7 @@ <argument index="1" name="position" type="Vector2"> </argument> <description> - Sets the position of the control point leading to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. + Sets the position of the control point leading to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. </description> </method> <method name="set_point_out"> @@ -163,7 +163,7 @@ <argument index="1" name="position" type="Vector2"> </argument> <description> - Sets the position of the control point leading out of the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. + Sets the position of the control point leading out of the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. </description> </method> <method name="set_point_position"> diff --git a/doc/classes/Curve3D.xml b/doc/classes/Curve3D.xml index fe454d90cc..a6a0e0c33d 100644 --- a/doc/classes/Curve3D.xml +++ b/doc/classes/Curve3D.xml @@ -95,7 +95,7 @@ <argument index="0" name="idx" type="int"> </argument> <description> - Returns the position of the control point leading to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0, 0)[/code]. + Returns the position of the control point leading to the vertex [code]idx[/code]. The returned position is relative to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0, 0)[/code]. </description> </method> <method name="get_point_out" qualifiers="const"> @@ -104,7 +104,7 @@ <argument index="0" name="idx" type="int"> </argument> <description> - Returns the position of the control point leading out of the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0, 0)[/code]. + Returns the position of the control point leading out of the vertex [code]idx[/code]. The returned position is relative to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0, 0)[/code]. </description> </method> <method name="get_point_position" qualifiers="const"> @@ -189,7 +189,7 @@ <argument index="1" name="position" type="Vector3"> </argument> <description> - Sets the position of the control point leading to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. + Sets the position of the control point leading to the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. </description> </method> <method name="set_point_out"> @@ -200,7 +200,7 @@ <argument index="1" name="position" type="Vector3"> </argument> <description> - Sets the position of the control point leading out of the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. + Sets the position of the control point leading out of the vertex [code]idx[/code]. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. </description> </method> <method name="set_point_position"> diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml index dc38fdf0e8..cd0b5ac027 100644 --- a/doc/classes/Dictionary.xml +++ b/doc/classes/Dictionary.xml @@ -11,17 +11,28 @@ Creating a dictionary: [codeblocks] [gdscript] - var my_dir = {} # Creates an empty dictionary. - var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} - var another_dir = { - key1: value1, - key2: value2, - key3: value3, + var my_dict = {} # Creates an empty dictionary. + + var dict_variable_key = "Another key name" + var dict_variable_value = "value2" + var another_dict = { + "Some key name": "value1", + dict_variable_key: dict_variable_value, + } + + var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} + + # Alternative Lua-style syntax. + # Doesn't require quotes around keys, but only string constants can be used as key names. + # Additionally, key names must start with a letter or an underscore. + # Here, `some_key` is a string literal, not a variable! + another_dict = { + some_key = 42, } [/gdscript] [csharp] - var myDir = new Godot.Collections.Dictionary(); // Creates an empty dictionary. - var pointsDir = new Godot.Collections.Dictionary + var myDict = new Godot.Collections.Dictionary(); // Creates an empty dictionary. + var pointsDict = new Godot.Collections.Dictionary { {"White", 50}, {"Yellow", 75}, @@ -33,15 +44,15 @@ [codeblocks] [gdscript] export(string, "White", "Yellow", "Orange") var my_color - var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} + var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} func _ready(): # We can't use dot syntax here as `my_color` is a variable. - var points = points_dir[my_color] + var points = points_dict[my_color] [/gdscript] [csharp] [Export(PropertyHint.Enum, "White,Yellow,Orange")] public string MyColor { get; set; } - public Godot.Collections.Dictionary pointsDir = new Godot.Collections.Dictionary + public Godot.Collections.Dictionary pointsDict = new Godot.Collections.Dictionary { {"White", 50}, {"Yellow", 75}, @@ -50,7 +61,7 @@ public override void _Ready() { - int points = (int)pointsDir[MyColor]; + int points = (int)pointsDict[MyColor]; } [/csharp] [/codeblocks] @@ -58,7 +69,7 @@ Dictionaries can contain more complex data: [codeblocks] [gdscript] - my_dir = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key. + my_dict = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key. [/gdscript] [csharp] var myDir = new Godot.Collections.Dictionary @@ -70,8 +81,8 @@ To add a key to an existing dictionary, access it like an existing key and assign to it: [codeblocks] [gdscript] - var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} - points_dir["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value. + var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} + points_dict["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value. [/gdscript] [csharp] var pointsDir = new Godot.Collections.Dictionary @@ -80,7 +91,7 @@ {"Yellow", 75}, {"Orange", 100} }; - pointsDir["blue"] = 150; // Add "Blue" as a key and assign 150 as its value. + pointsDict["blue"] = 150; // Add "Blue" as a key and assign 150 as its value. [/csharp] [/codeblocks] Finally, dictionaries can contain different types of keys and values in the same dictionary: @@ -89,22 +100,22 @@ # This is a valid dictionary. # To access the string "Nested value" below, use `my_dir.sub_dir.sub_key` or `my_dir["sub_dir"]["sub_key"]`. # Indexing styles can be mixed and matched depending on your needs. - var my_dir = { + var my_dict = { "String Key": 5, 4: [1, 2, 3], 7: "Hello", - "sub_dir": {"sub_key": "Nested value"}, + "sub_dict": {"sub_key": "Nested value"}, } [/gdscript] [csharp] // This is a valid dictionary. // To access the string "Nested value" below, use `my_dir.sub_dir.sub_key` or `my_dir["sub_dir"]["sub_key"]`. // Indexing styles can be mixed and matched depending on your needs. - var myDir = new Godot.Collections.Dictionary { + var myDict = new Godot.Collections.Dictionary { {"String Key", 5}, {4, new Godot.Collections.Array{1,2,3}}, {7, "Hello"}, - {"sub_dir", new Godot.Collections.Dictionary{{"sub_key", "Nested value"}}} + {"sub_dict", new Godot.Collections.Dictionary{{"sub_key", "Nested value"}}} }; [/csharp] [/codeblocks] @@ -117,11 +128,11 @@ func compare_arrays(): print(array1 == array2) # Will print true. - var dir1 = {"a": 1, "b": 2, "c": 3} - var dir2 = {"a": 1, "b": 2, "c": 3} + var dict1 = {"a": 1, "b": 2, "c": 3} + var dict2 = {"a": 1, "b": 2, "c": 3} func compare_dictionaries(): - print(dir1 == dir2) # Will NOT print true. + print(dict1 == dict2) # Will NOT print true. [/gdscript] [csharp] // You have to use GD.Hash(). @@ -135,35 +146,36 @@ GD.Print(GD.Hash(array1) == GD.Hash(array2)); // Will print true. } - public Godot.Collections.Dictionary dir1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; - public Godot.Collections.Dictionary dir2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; + public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; + public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; public void CompareDictionaries() { - GD.Print(dir1 == dir2); // Will NOT print true. + GD.Print(dict1 == dict2); // Will NOT print true. } [/csharp] [/codeblocks] You need to first calculate the dictionary's hash with [method hash] before you can compare them: [codeblocks] [gdscript] - var dir1 = {"a": 1, "b": 2, "c": 3} - var dir2 = {"a": 1, "b": 2, "c": 3} + var dict1 = {"a": 1, "b": 2, "c": 3} + var dict2 = {"a": 1, "b": 2, "c": 3} func compare_dictionaries(): - print(dir1.hash() == dir2.hash()) # Will print true. + print(dict1.hash() == dict2.hash()) # Will print true. [/gdscript] [csharp] // You have to use GD.Hash(). - public Godot.Collections.Dictionary dir1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; - public Godot.Collections.Dictionary dir2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; + public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; + public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; public void CompareDictionaries() { - GD.Print(GD.Hash(dir1) == GD.Hash(dir2)); // Will print true. + GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Will print true. } [/csharp] [/codeblocks] + [b]Note:[/b] When declaring a dictionary with [code]const[/code], the dictionary itself can still be mutated by defining the values of individual keys. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized. </description> <tutorials> <link title="GDScript basics: Dictionary">https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_basics.html#dictionary</link> @@ -322,7 +334,7 @@ <return type="int"> </return> <description> - Returns the size of the dictionary (in pairs). + Returns the number of keys in the dictionary. </description> </method> <method name="values"> diff --git a/doc/classes/EditorNode3DGizmoPlugin.xml b/doc/classes/EditorNode3DGizmoPlugin.xml index 4dea1bb645..322cff4e43 100644 --- a/doc/classes/EditorNode3DGizmoPlugin.xml +++ b/doc/classes/EditorNode3DGizmoPlugin.xml @@ -59,8 +59,11 @@ </argument> <argument index="1" name="billboard" type="bool" default="false"> </argument> + <argument index="2" name="texture" type="Texture2D" default="null"> + </argument> <description> Creates a handle material with its variants (selected and/or editable) and adds them to the internal material list. They can then be accessed with [method get_material] and used in [method EditorNode3DGizmo.add_handles]. Should not be overridden. + You can optionally provide a texture to use instead of the default icon. </description> </method> <method name="create_icon_material"> @@ -122,7 +125,7 @@ </return> <argument index="0" name="name" type="String"> </argument> - <argument index="1" name="gizmo" type="EditorNode3DGizmo"> + <argument index="1" name="gizmo" type="EditorNode3DGizmo" default="null"> </argument> <description> Gets material from the internal list of materials. If an [EditorNode3DGizmo] is provided, it will try to get the corresponding variant (selected and/or editable). diff --git a/doc/classes/File.xml b/doc/classes/File.xml index ada57a8114..2f7ac551cf 100644 --- a/doc/classes/File.xml +++ b/doc/classes/File.xml @@ -6,7 +6,8 @@ <description> File type. This is used to permanently store data into the user device's file system and to read from it. This can be used to store game save data or player configuration files, for example. Here's a sample on how to write and read from a file: - [codeblock] + [codeblocks] + [gdscript] func save(content): var file = File.new() file.open("user://save_game.dat", File.WRITE) @@ -19,7 +20,26 @@ var content = file.get_as_text() file.close() return content - [/codeblock] + [/gdscript] + [csharp] + public void Save(string content) + { + var file = new File(); + file.Open("user://save_game.dat", File.ModeFlags.Write); + file.StoreString(content); + file.Close(); + } + + public string Load() + { + var file = new File(); + file.Open("user://save_game.dat", File.ModeFlags.Read); + string content = file.GetAsText(); + file.Close(); + return content; + } + [/csharp] + [/codeblocks] In the example above, the file will be saved in the user data folder as specified in the [url=https://docs.godotengine.org/en/latest/tutorials/io/data_paths.html]Data paths[/url] documentation. [b]Note:[/b] To access project resources once exported, it is recommended to use [ResourceLoader] instead of the [File] API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. </description> @@ -303,7 +323,8 @@ Stores an integer as 16 bits in the file. [b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^16 - 1][/code]. Any other value will overflow and wrap around. To store a signed integer, use [method store_64] or store a signed integer from the interval [code][-2^15, 2^15 - 1][/code] (i.e. keeping one bit for the signedness) and compute its sign manually when reading. For example: - [codeblock] + [codeblocks] + [gdscript] const MAX_15B = 1 << 15 const MAX_16B = 1 << 16 @@ -320,7 +341,22 @@ var read2 = f.get_16() # 121 var converted1 = unsigned16_to_signed(read1) # -42 var converted2 = unsigned16_to_signed(read2) # 121 - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + var f = new File(); + f.Open("user://file.dat", File.ModeFlags.WriteRead); + f.Store16(unchecked((ushort)-42)); // This wraps around and stores 65494 (2^16 - 42). + f.Store16(121); // In bounds, will store 121. + f.Seek(0); // Go back to start to read the stored value. + ushort read1 = f.Get16(); // 65494 + ushort read2 = f.Get16(); // 121 + short converted1 = BitConverter.ToInt16(BitConverter.GetBytes(read1), 0); // -42 + short converted2 = BitConverter.ToInt16(BitConverter.GetBytes(read2), 0); // 121 + } + [/csharp] + [/codeblocks] </description> </method> <method name="store_32"> diff --git a/doc/classes/Geometry2D.xml b/doc/classes/Geometry2D.xml index a6bcc1301b..4ff54d15ce 100644 --- a/doc/classes/Geometry2D.xml +++ b/doc/classes/Geometry2D.xml @@ -201,12 +201,21 @@ Each polygon's vertices will be rounded as determined by [code]join_type[/code], see [enum PolyJoinType]. The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling [method is_polygon_clockwise]. [b]Note:[/b] To translate the polygon's vertices specifically, multiply them to a [Transform2D]: - [codeblock] + [codeblocks] + [gdscript] var polygon = PackedVector2Array([Vector2(0, 0), Vector2(100, 0), Vector2(100, 100), Vector2(0, 100)]) var offset = Vector2(50, 50) polygon = Transform2D(0, offset) * polygon print(polygon) # prints [Vector2(50, 50), Vector2(150, 50), Vector2(150, 150), Vector2(50, 150)] - [/codeblock] + [/gdscript] + [csharp] + var polygon = new Vector2[] { new Vector2(0, 0), new Vector2(100, 0), new Vector2(100, 100), new Vector2(0, 100) }; + var offset = new Vector2(50, 50); + // TODO: This code is not valid right now. Ping @aaronfranke about it before Godot 4.0 is out. + //polygon = (Vector2[]) new Transform2D(0, offset).Xform(polygon); + //GD.Print(polygon); // prints [Vector2(50, 50), Vector2(150, 50), Vector2(150, 150), Vector2(50, 150)] + [/csharp] + [/codeblocks] </description> </method> <method name="offset_polyline"> diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index ec8ca7456a..b6594aac39 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -112,17 +112,31 @@ </argument> <description> Generates a GET/POST application/x-www-form-urlencoded style query string from a provided dictionary, e.g.: - [codeblock] + [codeblocks] + [gdscript] var fields = {"username": "user", "password": "pass"} var query_string = http_client.query_string_from_dict(fields) # Returns "username=user&password=pass" - [/codeblock] + [/gdscript] + [csharp] + var fields = new Godot.Collections.Dictionary { { "username", "user" }, { "password", "pass" } }; + string queryString = new HTTPClient().QueryStringFromDict(fields); + // Returns "username=user&password=pass" + [/csharp] + [/codeblocks] Furthermore, if a key has a [code]null[/code] value, only the key itself is added, without equal sign and value. If the value is an array, for each value in it a pair with the same key is added. - [codeblock] + [codeblocks] + [gdscript] var fields = {"single": 123, "not_valued": null, "multiple": [22, 33, 44]} var query_string = http_client.query_string_from_dict(fields) # Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44" - [/codeblock] + [/gdscript] + [csharp] + var fields = new Godot.Collections.Dictionary{{"single", 123}, {"notValued", null}, {"multiple", new Godot.Collections.Array{22, 33, 44}}}; + string queryString = new HTTPClient().QueryStringFromDict(fields); + // Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44" + [/csharp] + [/codeblocks] </description> </method> <method name="read_response_body_chunk"> @@ -147,12 +161,20 @@ Sends a request to the connected host. The URL parameter is just the part after the host, so for [code]http://somehost.com/index.php[/code], it is [code]index.php[/code]. Headers are HTTP request headers. For available HTTP methods, see [enum Method]. To create a POST request with query strings to push to the server, do: - [codeblock] + [codeblocks] + [gdscript] var fields = {"username" : "user", "password" : "pass"} var query_string = http_client.query_string_from_dict(fields) var headers = ["Content-Type: application/x-www-form-urlencoded", "Content-Length: " + str(query_string.length())] var result = http_client.request(http_client.METHOD_POST, "index.php", headers, query_string) - [/codeblock] + [/gdscript] + [csharp] + var fields = new Godot.Collections.Dictionary { { "username", "user" }, { "password", "pass" } }; + 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); + [/csharp] + [/codeblocks] [b]Note:[/b] The [code]request_data[/code] parameter is ignored if [code]method[/code] 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.http_escape] for an example. </description> </method> diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml index 6eae881ffe..f2ab93033a 100644 --- a/doc/classes/HTTPRequest.xml +++ b/doc/classes/HTTPRequest.xml @@ -7,7 +7,8 @@ A node with the ability to send HTTP requests. Uses [HTTPClient] internally. Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP. [b]Example of contacting a REST API and printing one of its returned fields:[/b] - [codeblock] + [codeblocks] + [gdscript] func _ready(): # Create an HTTP request node and connect its completion signal. var http_request = HTTPRequest.new() @@ -34,9 +35,48 @@ # Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org). print(response.headers["User-Agent"]) - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + // Create an HTTP request node and connect its completion signal. + var httpRequest = new HTTPRequest(); + AddChild(httpRequest); + httpRequest.Connect("request_completed", this, nameof(HttpRequestCompleted)); + + // Perform a GET request. The URL below returns JSON as of writing. + Error error = httpRequest.Request("https://httpbin.org/get"); + if (error != Error.Ok) + { + GD.PushError("An error occurred in the HTTP request."); + } + + // Perform a POST request. The URL below returns JSON as of writing. + // Note: Don't make simultaneous requests using a single HTTPRequest node. + // The snippet below is provided for reference only. + string[] body = { "name", "Godette" }; + // GDScript to_json is non existent, so we use JSON.Print() here. + error = httpRequest.Request("https://httpbin.org/post", null, true, HTTPClient.Method.Post, JSON.Print(body)); + if (error != Error.Ok) + { + GD.PushError("An error occurred in the HTTP request."); + } + } + + + // Called when the HTTP request is completed. + private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body) + { + // GDScript parse_json is non existent so we have to use JSON.parse, which has a slightly different syntax. + var response = JSON.Parse(body.GetStringFromUTF8()).Result as Godot.Collections.Dictionary; + // Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org). + GD.Print((response["headers"] as Godot.Collections.Dictionary)["User-Agent"]); + } + [/csharp] + [/codeblocks] [b]Example of loading and displaying an image using HTTPRequest:[/b] - [codeblock] + [codeblocks] + [gdscript] func _ready(): # Create an HTTP request node and connect its completion signal. var http_request = HTTPRequest.new() @@ -51,6 +91,9 @@ # Called when the HTTP request is completed. func _http_request_completed(result, response_code, headers, body): + if result != HTTPRequest.RESULT_SUCCESS: + push_error("Image couldn't be downloaded. Try a different image.") + var image = Image.new() var error = image.load_png_from_buffer(body) if error != OK: @@ -63,7 +106,48 @@ var texture_rect = TextureRect.new() add_child(texture_rect) texture_rect.texture = texture - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + // Create an HTTP request node and connect its completion signal. + var httpRequest = new HTTPRequest(); + AddChild(httpRequest); + httpRequest.Connect("request_completed", this, nameof(HttpRequestCompleted)); + + // Perform the HTTP request. The URL below returns a PNG image as of writing. + Error error = httpRequest.Request("https://via.placeholder.com/512"); + if (error != Error.Ok) + { + GD.PushError("An error occurred in the HTTP request."); + } + } + + + // Called when the HTTP request is completed. + private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body) + { + if (result != (int)HTTPRequest.Result.Success) + { + GD.PushError("Image couldn't be downloaded. Try a different image."); + } + var image = new Image(); + Error error = image.LoadPngFromBuffer(body); + if (error != Error.Ok) + { + GD.PushError("Couldn't load the image."); + } + + var texture = new ImageTexture(); + texture.CreateFromImage(image); + + // Display the image in a TextureRect node. + var textureRect = new TextureRect(); + AddChild(textureRect); + textureRect.Texture = texture; + } + [/csharp] + [/codeblocks] [b]Gzipped response bodies[/b]: HTTPRequest will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. [b]Note:[/b] When performing HTTP requests from a project exported to HTML5, keep in mind the remote server may not allow requests from foreign origins due to [url=https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS]CORS[/url]. If you host the server in question, you should modify its backend to allow requests from foreign origins by adding the [code]Access-Control-Allow-Origin: *[/code] HTTP header. diff --git a/doc/classes/HashingContext.xml b/doc/classes/HashingContext.xml index f8152c813e..e020293d76 100644 --- a/doc/classes/HashingContext.xml +++ b/doc/classes/HashingContext.xml @@ -6,8 +6,9 @@ <description> The HashingContext class provides an interface for computing cryptographic hashes over multiple iterations. This is useful for example when computing hashes of big files (so you don't have to load them all in memory), network streams, and data streams in general (so you don't have to hold buffers). The [enum HashType] enum shows the supported hashing algorithms. - [codeblock] - const CHUNK_SIZE = 1024 + [codeblocks] + [gdscript] + const CHUNK_SIZE = 102 func hash_file(path): var ctx = HashingContext.new() @@ -26,7 +27,36 @@ var res = ctx.finish() # Print the result as hex string and array. printt(res.hex_encode(), Array(res)) - [/codeblock] + [/gdscript] + [csharp] + public const int ChunkSize = 1024; + + public void HashFile(string path) + { + var ctx = new HashingContext(); + var file = new File(); + // Start a SHA-256 context. + ctx.Start(HashingContext.HashType.Sha256); + // Check that file exists. + if (!file.FileExists(path)) + { + return; + } + // Open the file to hash. + file.Open(path, File.ModeFlags.Read); + // Update the context after reading each chunk. + while (!file.EofReached()) + { + ctx.Update(file.GetBuffer(ChunkSize)); + } + // Get the computed hash. + byte[] res = ctx.Finish(); + // Print the result as hex string and array. + + GD.PrintT(res.HexEncode(), res); + } + [/csharp] + [/codeblocks] [b]Note:[/b] Not available in HTML5 exports. </description> <tutorials> diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 3b108468de..b4325e822c 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -4,10 +4,12 @@ Image datatype. </brief_description> <description> - Native image datatype. Contains image data, which can be converted to a [Texture2D], and several functions to interact with it. The maximum width and height for an [Image] are [constant MAX_WIDTH] and [constant MAX_HEIGHT]. - [b]Note:[/b] The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images will fail to import. + Native image datatype. Contains image data which can be converted to an [ImageTexture] and provides commonly used [i]image processing[/i] methods. The maximum width and height for an [Image] are [constant MAX_WIDTH] and [constant MAX_HEIGHT]. + An [Image] cannot be assigned to a [code]texture[/code] property of an object directly (such as [Sprite2D]), and has to be converted manually to an [ImageTexture] first. + [b]Note:[/b] The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images may fail to import. </description> <tutorials> + <link title="Importing images">https://docs.godotengine.org/en/latest/getting_started/workflow/assets/importing_images.html</link> </tutorials> <methods> <method name="blend_rect"> @@ -267,16 +269,18 @@ <argument index="1" name="y" type="int"> </argument> <description> - Returns the color of the pixel at [code](x, y)[/code]. This is the same as [method get_pixelv], but with two integer arguments instead of a [Vector2] argument. + Returns the color of the pixel at [code](x, y)[/code]. + This is the same as [method get_pixelv], but with two integer arguments instead of a [Vector2i] argument. </description> </method> <method name="get_pixelv" qualifiers="const"> <return type="Color"> </return> - <argument index="0" name="src" type="Vector2"> + <argument index="0" name="point" type="Vector2i"> </argument> <description> - Returns the color of the pixel at [code]src[/code]. This is the same as [method get_pixel], but with a [Vector2] argument instead of two integer arguments. + Returns the color of the pixel at [code]point[/code]. + This is the same as [method get_pixel], but with a [Vector2i] argument instead of two integer arguments. </description> </method> <method name="get_rect" qualifiers="const"> @@ -344,6 +348,8 @@ </argument> <description> Loads an image from file [code]path[/code]. See [url=https://docs.godotengine.org/en/latest/getting_started/workflow/assets/importing_images.html#supported-image-formats]Supported image formats[/url] for a list of supported image formats and limitations. + [b]Warning:[/b] This method should only be used in the editor or in cases when you need to load external images at run-time, such as images located at the [code]user://[/code] directory, and may not work in exported projects. + See also [ImageTexture] description for usage examples. </description> </method> <method name="load_bmp_from_buffer"> @@ -471,28 +477,56 @@ <argument index="2" name="color" type="Color"> </argument> <description> - Sets the [Color] of the pixel at [code](x, y)[/code]. Example: - [codeblock] + Sets the [Color] of the pixel at [code](x, y)[/code] to [code]color[/code]. Example: + [codeblocks] + [gdscript] + var img_width = 10 + var img_height = 5 var img = Image.new() img.create(img_width, img_height, false, Image.FORMAT_RGBA8) - img.set_pixel(x, y, color) - [/codeblock] + + img.set_pixel(1, 2, Color.red) # Sets the color at (1, 2) to red. + [/gdscript] + [csharp] + int imgWidth = 10; + int imgHeight = 5; + var img = new Image(); + img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + + img.SetPixel(1, 2, Colors.Red); // Sets the color at (1, 2) to red. + [/csharp] + [/codeblocks] + This is the same as [method set_pixelv], but with a two integer arguments instead of a [Vector2i] argument. </description> </method> <method name="set_pixelv"> <return type="void"> </return> - <argument index="0" name="dst" type="Vector2"> + <argument index="0" name="point" type="Vector2i"> </argument> <argument index="1" name="color" type="Color"> </argument> <description> - Sets the [Color] of the pixel at [code](dst.x, dst.y)[/code]. Note that the [code]dst[/code] values must be integers. Example: - [codeblock] + Sets the [Color] of the pixel at [code]point[/code] to [code]color[/code]. Example: + [codeblocks] + [gdscript] + var img_width = 10 + var img_height = 5 var img = Image.new() img.create(img_width, img_height, false, Image.FORMAT_RGBA8) - img.set_pixelv(Vector2(x, y), color) - [/codeblock] + + img.set_pixelv(Vector2i(1, 2), Color.red) # Sets the color at (1, 2) to red. + [/gdscript] + [csharp] + int imgWidth = 10; + int imgHeight = 5; + var img = new Image(); + img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + + img.SetPixelv(new Vector2i(1, 2), Colors.Red); // Sets the color at (1, 2) to red. + [/csharp] + [/codeblocks] + This is the same as [method set_pixel], but with a [Vector2i] argument instead of two integer arguments. </description> </method> <method name="shrink_x2"> diff --git a/doc/classes/ImageTexture.xml b/doc/classes/ImageTexture.xml index d122d74e85..2bea482bc1 100644 --- a/doc/classes/ImageTexture.xml +++ b/doc/classes/ImageTexture.xml @@ -4,10 +4,31 @@ A [Texture2D] based on an [Image]. </brief_description> <description> - A [Texture2D] based on an [Image]. Can be created from an [Image] with [method create_from_image]. - [b]Note:[/b] The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images will fail to import. + A [Texture2D] based on an [Image]. For an image to be displayed, an [ImageTexture] has to be created from it using the [method create_from_image] method: + [codeblock] + var texture = ImageTexture.new() + var image = Image.new() + image.load("res://icon.png") + texture.create_from_image(image) + $Sprite2D.texture = texture + [/codeblock] + This way, textures can be created at run-time by loading images both from within the editor and externally. + [b]Warning:[/b] Prefer to load imported textures with [method @GDScript.load] over loading them from within the filesystem dynamically with [method Image.load], as it may not work in exported projects: + [codeblock] + var texture = load("res://icon.png") + $Sprite2D.texture = texture + [/codeblock] + This is because images have to be imported as [StreamTexture2D] first to be loaded with [method @GDScript.load]. If you'd still like to load an image file just like any other [Resource], import it as an [Image] resource instead, and then load it normally using the [method @GDScript.load] method. + But do note that the image data can still be retrieved from an imported texture as well using the [method Texture2D.get_data] method, which returns a copy of the data: + [codeblock] + var texture = load("res://icon.png") + var image : Image = texture.get_data() + [/codeblock] + An [ImageTexture] is not meant to be operated from within the editor interface directly, and is mostly useful for rendering images on screen dynamically via code. If you need to generate images procedurally from within the editor, consider saving and importing images as custom texture resources implementing a new [EditorImportPlugin]. + [b]Note:[/b] The maximum texture size is 16384×16384 pixels due to graphics hardware limitations. </description> <tutorials> + <link title="Importing images">https://docs.godotengine.org/en/latest/tutorials/assets_pipeline/importing_images.html</link> </tutorials> <methods> <method name="create_from_image"> @@ -16,14 +37,14 @@ <argument index="0" name="image" type="Image"> </argument> <description> - Create a new [ImageTexture] from an [Image]. + Initializes the texture by allocating and setting the data from an [Image]. </description> </method> <method name="get_format" qualifiers="const"> <return type="int" enum="Image.Format"> </return> <description> - Returns the format of the [ImageTexture], one of [enum Image.Format]. + Returns the format of the texture, one of [enum Image.Format]. </description> </method> <method name="set_size_override"> @@ -32,7 +53,7 @@ <argument index="0" name="size" type="Vector2"> </argument> <description> - Resizes the [ImageTexture] to the specified dimensions. + Resizes the texture to the specified dimensions. </description> </method> <method name="update"> @@ -43,7 +64,9 @@ <argument index="1" name="immediate" type="bool" default="false"> </argument> <description> - Replaces the texture's data with a new [code]image[/code]. If [code]immediate[/code] is [code]true[/code], it will take effect immediately after the call. + Replaces the texture's data with a new [Image]. If [code]immediate[/code] is [code]true[/code], it will take effect immediately after the call. + [b]Note:[/b] The texture has to be initialized first with the [method create_from_image] method before it can be updated. The new image dimensions, format, and mipmaps configuration should match the existing texture's image configuration, otherwise it has to be re-created with the [method create_from_image] method. + Use this method over [method create_from_image] if you need to update the texture frequently, which is faster than allocating additional memory for a new texture each time. </description> </method> </methods> diff --git a/doc/classes/Input.xml b/doc/classes/Input.xml index fb0ed8ff62..cfb3e8d981 100644 --- a/doc/classes/Input.xml +++ b/doc/classes/Input.xml @@ -49,11 +49,20 @@ <return type="Vector3"> </return> <description> - Returns the acceleration of the device's accelerometer, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. + Returns the acceleration of the device's accelerometer sensor, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. Note this method returns an empty [Vector3] when running from the editor even when your device has an accelerometer. You must export your project to a supported device to read values from the accelerometer. [b]Note:[/b] This method only works on iOS, Android, and UWP. On other platforms, it always returns [constant Vector3.ZERO]. </description> </method> + <method name="get_action_raw_strength" qualifiers="const"> + <return type="float"> + </return> + <argument index="0" name="action" type="StringName"> + </argument> + <description> + Returns a value between 0 and 1 representing the raw intensity of the given action, ignoring the action's deadzone. In most cases, you should use [method get_action_strength] instead. + </description> + </method> <method name="get_action_strength" qualifiers="const"> <return type="float"> </return> @@ -63,6 +72,18 @@ Returns a value between 0 and 1 representing the intensity of the given action. In a joypad, for example, the further away the axis (analog sticks or L2, R2 triggers) is from the dead zone, the closer the value will be to 1. If the action is mapped to a control that has no axis as the keyboard, the value returned will be 0 or 1. </description> </method> + <method name="get_axis" qualifiers="const"> + <return type="float"> + </return> + <argument index="0" name="negative_action" type="StringName"> + </argument> + <argument index="1" name="positive_action" type="StringName"> + </argument> + <description> + Get axis input by specifying two actions, one negative and one positive. + This is a horthand for writing [code]Input.get_action_strength("positive_action") - Input.get_action_strength("negative_action")[/code]. + </description> + </method> <method name="get_connected_joypads"> <return type="Array"> </return> @@ -81,7 +102,7 @@ <return type="Vector3"> </return> <description> - Returns the gravity of the device's accelerometer, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. + Returns the gravity of the device's accelerometer sensor, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. [b]Note:[/b] This method only works on Android and iOS. On other platforms, it always returns [constant Vector3.ZERO]. </description> </method> @@ -89,8 +110,8 @@ <return type="Vector3"> </return> <description> - Returns the rotation rate in rad/s around a device's X, Y, and Z axes of the gyroscope, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. - [b]Note:[/b] This method only works on Android. On other platforms, it always returns [constant Vector3.ZERO]. + Returns the rotation rate in rad/s around a device's X, Y, and Z axes of the gyroscope sensor, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. + [b]Note:[/b] This method only works on Android and iOS. On other platforms, it always returns [constant Vector3.ZERO]. </description> </method> <method name="get_joy_axis" qualifiers="const"> @@ -104,42 +125,6 @@ Returns the current value of the joypad axis at given index (see [enum JoyAxisList]). </description> </method> - <method name="get_joy_axis_index_from_string"> - <return type="int"> - </return> - <argument index="0" name="axis" type="String"> - </argument> - <description> - Returns the index of the provided axis name. - </description> - </method> - <method name="get_joy_axis_string"> - <return type="String"> - </return> - <argument index="0" name="axis_index" type="int"> - </argument> - <description> - Receives a [enum JoyAxisList] axis and returns its equivalent name as a string. - </description> - </method> - <method name="get_joy_button_index_from_string"> - <return type="int"> - </return> - <argument index="0" name="button" type="String"> - </argument> - <description> - Returns the index of the provided button name. - </description> - </method> - <method name="get_joy_button_string"> - <return type="String"> - </return> - <argument index="0" name="button_index" type="int"> - </argument> - <description> - Receives a gamepad button from [enum JoyButtonList] and returns its equivalent name as a string. - </description> - </method> <method name="get_joy_guid" qualifiers="const"> <return type="String"> </return> @@ -187,8 +172,8 @@ <return type="Vector3"> </return> <description> - Returns the the magnetic field strength in micro-Tesla for all axes of the device's magnetometer, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. - [b]Note:[/b] This method only works on Android and UWP. On other platforms, it always returns [constant Vector3.ZERO]. + Returns the the magnetic field strength in micro-Tesla for all axes of the device's magnetometer sensor, if the device has one. Otherwise, the method returns [constant Vector3.ZERO]. + [b]Note:[/b] This method only works on Android, iOS and UWP. On other platforms, it always returns [constant Vector3.ZERO]. </description> </method> <method name="get_mouse_button_mask" qualifiers="const"> @@ -205,6 +190,25 @@ Returns the mouse mode. See the constants for more information. </description> </method> + <method name="get_vector" qualifiers="const"> + <return type="Vector2"> + </return> + <argument index="0" name="negative_x" type="StringName"> + </argument> + <argument index="1" name="positive_x" type="StringName"> + </argument> + <argument index="2" name="negative_y" type="StringName"> + </argument> + <argument index="3" name="positive_y" type="StringName"> + </argument> + <argument index="4" name="deadzone" type="float" default="-1.0"> + </argument> + <description> + Get vector input by specifying four actions, two for the X axis and two for the Y axis, negative and positive. + This method is useful when getting vector input, such as from a joystick, directional pad, arrows, or WASD. The vector has its length limited to 1 and has a circular deadzone, which is useful for using vector input as movement. + By default, the deadzone is automatically calculated from the average of the action deadzones. However, you can override the deadzone to be whatever you want (on the range of 0 to 1). + </description> + </method> <method name="is_action_just_pressed" qualifiers="const"> <return type="bool"> </return> @@ -295,12 +299,20 @@ <description> Feeds an [InputEvent] to the game. Can be used to artificially trigger input events from code. Also generates [method Node._input] calls. Example: - [codeblock] - var a = InputEventAction.new() - a.action = "ui_cancel" - a.pressed = true - Input.parse_input_event(a) - [/codeblock] + [codeblocks] + [gdscript] + var cancel_event = InputEventAction.new() + cancel_event.action = "ui_cancel" + cancel_event.pressed = true + Input.parse_input_event(cancel_event) + [/gdscript] + [csharp] + var cancelEvent = new InputEventAction(); + cancelEvent.Action = "ui_cancel"; + cancelEvent.Pressed = true; + Input.ParseInputEvent(cancelEvent); + [/csharp] + [/codeblocks] </description> </method> <method name="remove_joy_mapping"> @@ -391,7 +403,7 @@ </argument> <description> Vibrate Android and iOS devices. - [b]Note:[/b] It needs VIBRATE permission for Android at export settings. iOS does not support duration. + [b]Note:[/b] It needs [code]VIBRATE[/code] permission for Android at export settings. iOS does not support duration. </description> </method> <method name="warp_mouse_position"> diff --git a/doc/classes/InputEventWithModifiers.xml b/doc/classes/InputEventWithModifiers.xml index 667879a922..dd782209e5 100644 --- a/doc/classes/InputEventWithModifiers.xml +++ b/doc/classes/InputEventWithModifiers.xml @@ -27,6 +27,10 @@ <member name="shift" type="bool" setter="set_shift" getter="get_shift" default="false"> State of the [kbd]Shift[/kbd] modifier. </member> + <member name="store_command" type="bool" setter="set_store_command" getter="is_storing_command" default="true"> + If [code]true[/code], pressing [kbd]Cmd[/kbd] on macOS or [kbd]Ctrl[/kbd] on all other platforms will both be serialized as [member command]. If [code]false[/code], those same keys will be serialized as [member meta] on macOS and [member control] on all other platforms. + This aids with cross-platform compatibility when developing e.g. on Windows for macOS, or vice-versa. + </member> </members> <constants> </constants> diff --git a/doc/classes/InputMap.xml b/doc/classes/InputMap.xml index 062ac3869d..49d29b3a53 100644 --- a/doc/classes/InputMap.xml +++ b/doc/classes/InputMap.xml @@ -120,7 +120,7 @@ Returns [code]true[/code] if the [InputMap] has a registered action with the given name. </description> </method> - <method name="load_from_globals"> + <method name="load_from_project_settings"> <return type="void"> </return> <description> diff --git a/doc/classes/InstancePlaceholder.xml b/doc/classes/InstancePlaceholder.xml index 39827f6604..defd23afb1 100644 --- a/doc/classes/InstancePlaceholder.xml +++ b/doc/classes/InstancePlaceholder.xml @@ -18,13 +18,14 @@ <argument index="1" name="custom_scene" type="PackedScene" default="null"> </argument> <description> + Not thread-safe. Use [method Object.call_deferred] if calling from a thread. </description> </method> <method name="get_instance_path" qualifiers="const"> <return type="String"> </return> <description> - Gets the path to the [PackedScene] resource file that is loaded by default when calling [method create_instance]. + Gets the path to the [PackedScene] resource file that is loaded by default when calling [method create_instance]. Not thread-safe. Use [method Object.call_deferred] if calling from a thread. </description> </method> <method name="get_stored_values"> diff --git a/doc/classes/ItemList.xml b/doc/classes/ItemList.xml index 25420bd77b..fd8bfb4ece 100644 --- a/doc/classes/ItemList.xml +++ b/doc/classes/ItemList.xml @@ -247,11 +247,16 @@ <argument index="1" name="custom_bg_color" type="Color"> </argument> <description> - Sets the background color of the item specified by [code]idx[/code] index to the specified [Color]. - [codeblock] - var some_string = "Some text" - some_string.set_item_custom_bg_color(0,Color(1, 0, 0, 1) # This will set the background color of the first item of the control to red. - [/codeblock] + [codeblocks] + [gdscript] + var itemList = ItemList.new() + some_string.set_item_custom_bg_color(0, Color.red) # This will set the background color of the first item of the control to red. + [/gdscript] + [csharp] + var itemList = new ItemList(); + itemList.SetItemCustomBgColor(0, Colors.Red); // This will set the background color of the first item of the control to red. + [/csharp] + [/codeblocks] </description> </method> <method name="set_item_custom_fg_color"> @@ -263,10 +268,16 @@ </argument> <description> Sets the foreground color of the item specified by [code]idx[/code] index to the specified [Color]. - [codeblock] - var some_string = "Some text" - some_string.set_item_custom_fg_color(0,Color(1, 0, 0, 1) # This will set the foreground color of the first item of the control to red. - [/codeblock] + [codeblocks] + [gdscript] + var item_list = ItemList.new() + item_list.set_item_custom_fg_color(0, Color.red) # This will set the foreground color of the first item of the control to red. + [/gdscript] + [csharp] + var itemList = new ItemList(); + itemList.SetItemCustomFgColor(0, Colors.Red); // This will set the foreground color of the first item of the control to red. + [/csharp] + [/codeblocks] </description> </method> <method name="set_item_disabled"> diff --git a/doc/classes/JSONParseResult.xml b/doc/classes/JSONParseResult.xml index 4dbceb35e9..991ebcd7a0 100644 --- a/doc/classes/JSONParseResult.xml +++ b/doc/classes/JSONParseResult.xml @@ -24,13 +24,26 @@ A [Variant] containing the parsed JSON. Use [method @GDScript.typeof] or the [code]is[/code] keyword to check if it is what you expect. For example, if the JSON source starts with curly braces ([code]{}[/code]), a [Dictionary] will be returned. If the JSON source starts with brackets ([code][][/code]), an [Array] will be returned. [b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, parsing a JSON text will convert all numerical values to [float] types. [b]Note:[/b] JSON objects do not preserve key order like Godot dictionaries, thus, you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements: - [codeblock] + [codeblocks] + [gdscript] var p = JSON.parse('["hello", "world", "!"]') if typeof(p.result) == TYPE_ARRAY: print(p.result[0]) # Prints "hello" else: push_error("Unexpected results.") - [/codeblock] + [/gdscript] + [csharp] + JSONParseResult p = JSON.Parse("[\"hello\"], \"world\", \"!\"]"); + if (p.Result is Godot.Collections.Array) + { + GD.Print((p.Result as Godot.Collections.Array)[0]); // Prints "hello" + } + else + { + GD.PushError("Unexpected results."); + } + [/csharp] + [/codeblocks] </member> </members> <constants> diff --git a/doc/classes/JSONParser.xml b/doc/classes/JSONParser.xml new file mode 100644 index 0000000000..31ba295418 --- /dev/null +++ b/doc/classes/JSONParser.xml @@ -0,0 +1,57 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="JSONParser" inherits="Reference" version="4.0"> + <brief_description> + </brief_description> + <description> + </description> + <tutorials> + </tutorials> + <methods> + <method name="decode_data"> + <return type="int" enum="Error"> + </return> + <argument index="0" name="data" type="Variant"> + </argument> + <argument index="1" name="indent" type="String" default=""""> + </argument> + <argument index="2" name="sort_keys" type="bool" default="true"> + </argument> + <description> + </description> + </method> + <method name="get_data" qualifiers="const"> + <return type="Variant"> + </return> + <description> + </description> + </method> + <method name="get_error_line" qualifiers="const"> + <return type="int"> + </return> + <description> + </description> + </method> + <method name="get_error_text" qualifiers="const"> + <return type="String"> + </return> + <description> + </description> + </method> + <method name="get_string" qualifiers="const"> + <return type="String"> + </return> + <description> + </description> + </method> + <method name="parse_string"> + <return type="int" enum="Error"> + </return> + <argument index="0" name="json_string" type="String"> + </argument> + <description> + </description> + </method> + </methods> + <constants> + </constants> +</class> diff --git a/doc/classes/KinematicBody2D.xml b/doc/classes/KinematicBody2D.xml index 425df00b6f..476b64a336 100644 --- a/doc/classes/KinematicBody2D.xml +++ b/doc/classes/KinematicBody2D.xml @@ -37,11 +37,20 @@ <description> Returns a [KinematicCollision2D], which contains information about a collision that occurred during the last call to [method move_and_slide] or [method move_and_slide_with_snap]. Since the body can collide several times in a single call to [method move_and_slide], you must specify the index of the collision in the range 0 to ([method get_slide_count] - 1). [b]Example usage:[/b] - [codeblock] + [codeblocks] + [gdscript] for i in get_slide_count(): var collision = get_slide_collision(i) print("Collided with: ", collision.collider.name) - [/codeblock] + [/gdscript] + [csharp] + for (int i = 0; i < GetSlideCount(); i++) + { + KinematicCollision2D collision = GetSlideCollision(i); + GD.Print("Collided with: ", (collision.Collider as Node).Name); + } + [/csharp] + [/codeblocks] </description> </method> <method name="get_slide_count" qualifiers="const"> diff --git a/doc/classes/LineEdit.xml b/doc/classes/LineEdit.xml index 5c2dffd538..b7211419e4 100644 --- a/doc/classes/LineEdit.xml +++ b/doc/classes/LineEdit.xml @@ -103,12 +103,20 @@ </argument> <description> Selects characters inside [LineEdit] between [code]from[/code] and [code]to[/code]. By default, [code]from[/code] is at the beginning and [code]to[/code] at the end. - [codeblock] + [codeblocks] + [gdscript] text = "Welcome" select() # Will select "Welcome". select(4) # Will select "ome". select(2, 5) # Will select "lco". - [/codeblock] + [/gdscript] + [csharp] + Text = "Welcome"; + Select(); // Will select "Welcome". + Select(4); // Will select "ome". + Select(2, 5); // Will select "lco". + [/csharp] + [/codeblocks] </description> </method> <method name="select_all"> diff --git a/doc/classes/MarginContainer.xml b/doc/classes/MarginContainer.xml index fb5f437239..c8eebd4677 100644 --- a/doc/classes/MarginContainer.xml +++ b/doc/classes/MarginContainer.xml @@ -6,13 +6,22 @@ <description> Adds a top, left, bottom, and right margin to all [Control] nodes that are direct children of the container. To control the [MarginContainer]'s margin, use the [code]margin_*[/code] theme properties listed below. [b]Note:[/b] Be careful, [Control] margin values are different than the constant margin values. If you want to change the custom margin values of the [MarginContainer] by code, you should use the following examples: - [codeblock] + [codeblocks] + [gdscript] var margin_value = 100 set("custom_constants/margin_top", margin_value) set("custom_constants/margin_left", margin_value) set("custom_constants/margin_bottom", margin_value) set("custom_constants/margin_right", margin_value) - [/codeblock] + [/gdscript] + [csharp] + int marginValue = 100; + Set("custom_constants/margin_top", marginValue); + Set("custom_constants/margin_left", marginValue); + Set("custom_constants/margin_bottom", marginValue); + Set("custom_constants/margin_right", marginValue); + [/csharp] + [/codeblocks] </description> <tutorials> </tutorials> diff --git a/doc/classes/MeshDataTool.xml b/doc/classes/MeshDataTool.xml index dcc3bbf2a6..e107b1a108 100644 --- a/doc/classes/MeshDataTool.xml +++ b/doc/classes/MeshDataTool.xml @@ -7,16 +7,44 @@ MeshDataTool provides access to individual vertices in a [Mesh]. It allows users to read and edit vertex data of meshes. It also creates an array of faces and edges. To use MeshDataTool, load a mesh with [method create_from_surface]. When you are finished editing the data commit the data to a mesh with [method commit_to_surface]. Below is an example of how MeshDataTool may be used. - [codeblock] + [codeblocks] + [gdscript] + var mesh = ArrayMesh.new() + mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, CubeMesh.new().get_mesh_arrays()) var mdt = MeshDataTool.new() mdt.create_from_surface(mesh, 0) for i in range(mdt.get_vertex_count()): var vertex = mdt.get_vertex(i) - ... + # In this example we extend the mesh by one unit, which results in seperated faces as it is flat shaded. + vertex += mdt.get_vertex_normal(i) + # Save your change. mdt.set_vertex(i, vertex) mesh.surface_remove(0) mdt.commit_to_surface(mesh) - [/codeblock] + var mi = MeshInstance.new() + mi.mesh = mesh + add_child(mi) + [/gdscript] + [csharp] + var mesh = new ArrayMesh(); + mesh.AddSurfaceFromArrays(Mesh.PrimitiveType.Triangles, new CubeMesh().GetMeshArrays()); + var mdt = new MeshDataTool(); + mdt.CreateFromSurface(mesh, 0); + for (var i = 0; i < mdt.GetVertexCount(); i++) + { + Vector3 vertex = mdt.GetVertex(i); + // In this example we extend the mesh by one unit, which results in seperated faces as it is flat shaded. + vertex += mdt.GetVertexNormal(i); + // Save your change. + mdt.SetVertex(i, vertex); + } + mesh.SurfaceRemove(0); + mdt.CommitToSurface(mesh); + var mi = new MeshInstance(); + mi.Mesh = mesh; + AddChild(mi); + [/csharp] + [/codeblocks] See also [ArrayMesh], [ImmediateGeometry3D] and [SurfaceTool] for procedural geometry generation. [b]Note:[/b] Godot uses clockwise [url=https://learnopengl.com/Advanced-OpenGL/Face-culling]winding order[/url] for front faces of triangle primitive modes. </description> diff --git a/doc/classes/NavigationPolygon.xml b/doc/classes/NavigationPolygon.xml index e75efa3b27..38921078d7 100644 --- a/doc/classes/NavigationPolygon.xml +++ b/doc/classes/NavigationPolygon.xml @@ -6,22 +6,41 @@ <description> There are two ways to create polygons. Either by using the [method add_outline] method, or using the [method add_polygon] method. Using [method add_outline]: - [codeblock] + [codeblocks] + [gdscript] var polygon = NavigationPolygon.new() var outline = PackedVector2Array([Vector2(0, 0), Vector2(0, 50), Vector2(50, 50), Vector2(50, 0)]) polygon.add_outline(outline) polygon.make_polygons_from_outlines() $NavigationRegion2D.navpoly = polygon - [/codeblock] + [/gdscript] + [csharp] + var polygon = new NavigationPolygon(); + var outline = new Vector2[] { new Vector2(0, 0), new Vector2(0, 50), new Vector2(50, 50), new Vector2(50, 0) }; + polygon.AddOutline(outline); + polygon.MakePolygonsFromOutlines(); + GetNode<NavigationRegion2D>("NavigationRegion2D").Navpoly = polygon; + [/csharp] + [/codeblocks] Using [method add_polygon] and indices of the vertices array. - [codeblock] + [codeblocks] + [gdscript] var polygon = NavigationPolygon.new() var vertices = PackedVector2Array([Vector2(0, 0), Vector2(0, 50), Vector2(50, 50), Vector2(50, 0)]) - polygon.set_vertices(vertices) + polygon.vertices = vertices var indices = PackedInt32Array(0, 3, 1) polygon.add_polygon(indices) $NavigationRegion2D.navpoly = polygon - [/codeblock] + [/gdscript] + [csharp] + var polygon = new NavigationPolygon(); + var vertices = new Vector2[] { new Vector2(0, 0), new Vector2(0, 50), new Vector2(50, 50), new Vector2(50, 0) }; + polygon.Vertices = vertices; + var indices = new int[] { 0, 3, 1 }; + polygon.AddPolygon(indices); + GetNode<NavigationRegion2D>("NavigationRegion2D").Navpoly = polygon; + [/csharp] + [/codeblocks] </description> <tutorials> <link title="2D Navigation Demo">https://godotengine.org/asset-library/asset/117</link> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 2e8b76865d..e3fc87ffb5 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -130,11 +130,22 @@ Adds a child 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 [code]legible_unique_name[/code] is [code]true[/code], the child node will have an human-readable name based on the name of the node being instanced instead of its type. [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: - [codeblock] + [codeblocks] + [gdscript] + var child_node = get_child(0) if child_node.get_parent(): child_node.get_parent().remove_child(child_node) add_child(child_node) - [/codeblock] + [/gdscript] + [csharp] + Node childNode = GetChild(0); + if (childNode.GetParent() != null) + { + childNode.GetParent().RemoveChild(childNode); + } + AddChild(childNode); + [/csharp] + [/codeblocks] If you need the child node to be added below a specific node in the list of children, use [method add_sibling] instead of this method. [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=https://godot.readthedocs.io/en/latest/tutorials/misc/running_code_in_the_editor.html]tool scripts[/url] and [url=https://godot.readthedocs.io/en/latest/tutorials/plugins/editor/index.html]editor plugins[/url]. If [method add_child] is called without setting [member owner], the newly added [Node] will not be visible in the scene tree, though it will be visible in the 2D/3D view. </description> @@ -275,12 +286,20 @@ /root/Swamp/Goblin [/codeblock] Possible paths are: - [codeblock] + [codeblocks] + [gdscript] get_node("Sword") get_node("Backpack/Dagger") get_node("../Swamp/Alligator") get_node("/root/MyGame") - [/codeblock] + [/gdscript] + [csharp] + GetNode("Sword"); + GetNode("Backpack/Dagger"); + GetNode("../Swamp/Alligator"); + GetNode("/root/MyGame"); + [/csharp] + [/codeblocks] </description> </method> <method name="get_node_and_resource"> @@ -292,11 +311,18 @@ 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: - [codeblock] + [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] - [/codeblock] + [/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] + [/csharp] + [/codeblocks] </description> </method> <method name="get_node_or_null" qualifiers="const"> @@ -756,7 +782,8 @@ <argument index="0" name="enable" type="bool"> </argument> <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' behaviour. + 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. </description> </method> <method name="set_process"> @@ -783,7 +810,8 @@ <argument index="0" name="enable" type="bool"> </argument> <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' behaviour. + 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. </description> </method> <method name="set_process_unhandled_input"> diff --git a/doc/classes/NodePath.xml b/doc/classes/NodePath.xml index 93ede047fd..36835d9e94 100644 --- a/doc/classes/NodePath.xml +++ b/doc/classes/NodePath.xml @@ -51,7 +51,7 @@ 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): [codeblock] - # Points to the Sprite2D node + # Points to the Sprite2D node. "Path2D/PathFollow2D/Sprite2D" # Points to the Sprite2D node and its "texture" resource. # get_node() would retrieve "Sprite2D", while get_node_and_resource() @@ -70,14 +70,23 @@ <return type="NodePath"> </return> <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). - [codeblock] - # This will be parsed as a node path to the "x" property in the "position" node + 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 from 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 + # This will be parsed as a node path to the "x" component of the "position" property in the current node. var property_path = node_path.get_as_property_path() print(property_path) # :position:x - [/codeblock] + [/gdscript] + [csharp] + // This will be parsed as a node path to the "x" property in the "position" node. + 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. + NodePath propertyPath = nodePath.GetAsPropertyPath(); + GD.Print(propertyPath); // :position:x + [/csharp] + [/codeblocks] </description> </method> <method name="get_concatenated_subnames"> @@ -85,10 +94,16 @@ </return> <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. - [codeblock] + [codeblocks] + [gdscript] var nodepath = NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path") print(nodepath.get_concatenated_subnames()) # texture:load_path - [/codeblock] + [/gdscript] + [csharp] + var nodepath = new NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path"); + GD.Print(nodepath.GetConcatenatedSubnames()); // texture:load_path + [/csharp] + [/codeblocks] </description> </method> <method name="get_name"> @@ -98,12 +113,20 @@ </argument> <description> Gets the node name indicated by [code]idx[/code] (0 to [method get_name_count]). - [codeblock] + [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 - [/codeblock] + [/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 + [/csharp] + [/codeblocks] </description> </method> <method name="get_name_count"> @@ -121,11 +144,18 @@ </argument> <description> Gets the resource or property name indicated by [code]idx[/code] (0 to [method get_subname_count]). - [codeblock] + [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 - [/codeblock] + [/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 + [/csharp] + [/codeblocks] </description> </method> <method name="get_subname_count"> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 1487c9e078..1d80695798 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -85,18 +85,36 @@ If [code]blocking[/code] is [code]false[/code], the Godot thread will continue while the new process runs. It is not possible to retrieve the shell output in non-blocking mode, so [code]output[/code] will be empty. The return value also depends on the blocking mode. When blocking, the method will return an exit code of the process. When non-blocking, the method returns a process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). If the process forking (non-blocking) or opening (blocking) fails, the method will return [code]-1[/code] or another exit code. Example of blocking mode and retrieving the shell output: - [codeblock] + [codeblocks] + [gdscript] var output = [] var exit_code = OS.execute("ls", ["-l", "/tmp"], true, output) - [/codeblock] + [/gdscript] + [csharp] + var output = new Godot.Collections.Array(); + int exitCode = OS.Execute("ls", new string[] {"-l", "/tmp"}, true, output); + [/csharp] + [/codeblocks] Example of non-blocking mode, running another instance of the project and storing its process ID: - [codeblock] + [codeblocks] + [gdscript] var pid = OS.execute(OS.get_executable_path(), [], false) - [/codeblock] + [/gdscript] + [csharp] + var pid = OS.Execute(OS.GetExecutablePath(), new string[] {}, false); + [/csharp] + [/codeblocks] If you wish to access a shell built-in or perform a composite command, a platform-specific shell can be invoked. For example: - [codeblock] + [codeblocks] + [gdscript] + var output = [] OS.execute("CMD.exe", ["/C", "cd %TEMP% && dir"], true, output) - [/codeblock] + [/gdscript] + [csharp] + var output = new Godot.Collections.Array(); + OS.Execute("CMD.exe", new string[] {"/C", "cd %TEMP% && dir"}, true, output); + [/csharp] + [/codeblocks] [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> @@ -118,13 +136,26 @@ You can also incorporate environment variables using the [method get_environment] method. You can set [code]editor/main_run_args[/code] in the Project Settings 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: - [codeblock] + [codeblocks] + [gdscript] var arguments = {} for argument in OS.get_cmdline_args(): if argument.find("=") > -1: var key_value = argument.split("=") arguments[key_value[0].lstrip("--")] = key_value[1] - [/codeblock] + [/gdscript] + [csharp] + var arguments = new Godot.Collections.Dictionary(); + foreach (var argument in OS.GetCmdlineArgs()) + { + if (argument.Find("=") > -1) + { + string[] keyValue = argument.Split("="); + arguments[keyValue[0].LStrip("--")] = keyValue[1]; + } + } + [/csharp] + [/codeblocks] </description> </method> <method name="get_connected_midi_inputs"> diff --git a/doc/classes/PCKPacker.xml b/doc/classes/PCKPacker.xml index 6b500d5ac3..e3c78e08f1 100644 --- a/doc/classes/PCKPacker.xml +++ b/doc/classes/PCKPacker.xml @@ -5,12 +5,20 @@ </brief_description> <description> The [PCKPacker] is used to create packages that can be loaded into a running project using [method ProjectSettings.load_resource_pack]. - [codeblock] + [codeblocks] + [gdscript] var packer = PCKPacker.new() packer.pck_start("test.pck") packer.add_file("res://text.txt", "text.txt") packer.flush() - [/codeblock] + [/gdscript] + [csharp] + var packer = new PCKPacker(); + packer.PckStart("test.pck"); + packer.AddFile("res://text.txt", "text.txt"); + packer.Flush(); + [/csharp] + [/codeblocks] The above [PCKPacker] creates package [code]test.pck[/code], then adds a file named [code]text.txt[/code] at the root of the package. </description> <tutorials> diff --git a/doc/classes/PackedByteArray.xml b/doc/classes/PackedByteArray.xml index 4a6893879d..91d066260b 100644 --- a/doc/classes/PackedByteArray.xml +++ b/doc/classes/PackedByteArray.xml @@ -135,10 +135,16 @@ </return> <description> Returns a hexadecimal representation of this array as a [String]. - [codeblock] + [codeblocks] + [gdscript] var array = PackedByteArray([11, 46, 255]) print(array.hex_encode()) # Prints: 0b2eff - [/codeblock] + [/gdscript] + [csharp] + var array = new byte[] {11, 46, 255}; + GD.Print(array.HexEncode()); // Prints: 0b2eff + [/csharp] + [/codeblocks] </description> </method> <method name="insert"> diff --git a/doc/classes/PackedScene.xml b/doc/classes/PackedScene.xml index be40ab05de..d15bcfd114 100644 --- a/doc/classes/PackedScene.xml +++ b/doc/classes/PackedScene.xml @@ -8,14 +8,23 @@ Can be used to save a node to a file. When saving, the node as well as all the node it owns get saved (see [code]owner[/code] property on [Node]). [b]Note:[/b] The node doesn't need to own itself. [b]Example of loading a saved scene:[/b] - [codeblock] - # Use `load()` instead of `preload()` if the path isn't known at compile-time. + [codeblocks] + [gdscript] + # Use load() instead of preload() if the path isn't known at compile-time. var scene = preload("res://scene.tscn").instance() # Add the node as a child of the node the script is attached to. add_child(scene) - [/codeblock] + [/gdscript] + [csharp] + // C# has no preload, so you have to always use ResourceLoader.Load<PackedScene>(). + var scene = ResourceLoader.Load<PackedScene>("res://scene.tscn").Instance(); + // Add the node as a child of the node the script is attached to. + AddChild(scene); + [/csharp] + [/codeblocks] [b]Example of saving a node with different owners:[/b] The following example creates 3 objects: [code]Node2D[/code] ([code]node[/code]), [code]RigidBody2D[/code] ([code]rigid[/code]) and [code]CollisionObject2D[/code] ([code]collision[/code]). [code]collision[/code] is a child of [code]rigid[/code] which is a child of [code]node[/code]. Only [code]rigid[/code] is owned by [code]node[/code] and [code]pack[/code] will therefore only save those two nodes, but not [code]collision[/code]. - [codeblock] + [codeblocks] + [gdscript] # Create the objects. var node = Node2D.new() var rigid = RigidBody2D.new() @@ -27,15 +36,41 @@ # Change owner of `rigid`, but not of `collision`. rigid.owner = node - var scene = PackedScene.new() + # Only `node` and `rigid` are now packed. var result = scene.pack(node) if result == OK: - var error = ResourceSaver.save("res://path/name.scn", scene) # Or "user://..." + var error = ResourceSaver.save("res://path/name.tscn", scene) # Or "user://..." if error != OK: push_error("An error occurred while saving the scene to disk.") - [/codeblock] + [/gdscript] + [csharp] + // Create the objects. + var node = new Node2D(); + var rigid = new RigidBody2D(); + var collision = new CollisionShape2D(); + + // Create the object hierarchy. + rigid.AddChild(collision); + node.AddChild(rigid); + + // Change owner of `rigid`, but not of `collision`. + rigid.Owner = node; + var scene = new PackedScene(); + + // Only `node` and `rigid` are now packed. + Error result = scene.Pack(node); + if (result == Error.Ok) + { + Error error = ResourceSaver.Save("res://path/name.tscn", scene); // Or "user://..." + if (error != Error.Ok) + { + GD.PushError("An error occurred while saving the scene to disk."); + } + } + [/csharp] + [/codeblocks] </description> <tutorials> <link title="2D Role Playing Game Demo">https://godotengine.org/asset-library/asset/520</link> diff --git a/doc/classes/PacketPeerUDP.xml b/doc/classes/PacketPeerUDP.xml index cab821b4c0..d7cf6cc8c6 100644 --- a/doc/classes/PacketPeerUDP.xml +++ b/doc/classes/PacketPeerUDP.xml @@ -124,17 +124,36 @@ <description> Waits for a packet to arrive on the listening port. See [method listen]. [b]Note:[/b] [method wait] can't be interrupted once it has been called. This can be worked around by allowing the other party to send a specific "death pill" packet like this: - [codeblock] - # Server - socket.set_dest_address("127.0.0.1", 789) - socket.put_packet("Time to stop".to_ascii()) + [codeblocks] + [gdscript] + socket = PacketPeerUDP.new() + # Server + socket.set_dest_address("127.0.0.1", 789) + socket.put_packet("Time to stop".to_ascii()) - # Client - while socket.wait() == OK: - var data = socket.get_packet().get_string_from_ascii() - if data == "Time to stop": - return - [/codeblock] + # Client + while socket.wait() == OK: + var data = socket.get_packet().get_string_from_ascii() + if data == "Time to stop": + return + [/gdscript] + [csharp] + var socket = new PacketPeerUDP(); + // Server + socket.SetDestAddress("127.0.0.1", 789); + socket.PutPacket("Time To Stop".ToAscii()); + + // Client + while (socket.Wait() == OK) + { + string data = socket.GetPacket().GetStringFromASCII(); + if (data == "Time to stop") + { + return; + } + } + [/csharp] + [/codeblocks] </description> </method> </methods> diff --git a/doc/classes/Performance.xml b/doc/classes/Performance.xml index 0a9079ce71..9e9c5063ae 100644 --- a/doc/classes/Performance.xml +++ b/doc/classes/Performance.xml @@ -24,14 +24,53 @@ </argument> <description> Adds a custom monitor with name same as id. You can specify the category of monitor using '/' in id. If there are more than one '/' then default category is used. Default category is "Custom". - [codeblock] - Performance.add_custom_monitor("MyCategory/MyMonitor", some_callable) # Adds monitor with name "MyName" to category "MyCategory" - Performance.add_custom_monitor("MyMonitor", some_callable) # Adds monitor with name "MyName" to category "Custom" - # Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different ids so above code is valid - Performance.add_custom_monitor("Custom/MyMonitor", some_callable) # Adds monitor with name "MyName" to category "Custom" - # Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different ids so above code is valid - Performance.add_custom_monitor("MyCategoryOne/MyCategoryTwo/MyMonitor", some_callable) # Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom" - [/codeblock] + [codeblocks] + [gdscript] + func _ready(): + var monitor_value = Callable(self, "get_monitor_value") + + # Adds monitor with name "MyName" to category "MyCategory". + Performance.add_custom_monitor("MyCategory/MyMonitor", monitor_value) + + # Adds monitor with name "MyName" to category "Custom". + # Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different ids so the code is valid. + Performance.add_custom_monitor("MyMonitor", monitor_value) + + # Adds monitor with name "MyName" to category "Custom". + # Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different ids so the code is valid. + Performance.add_custom_monitor("Custom/MyMonitor", monitor_value) + + # Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom". + Performance.add_custom_monitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitor_value) + + func get_monitor_value(): + return randi() % 25 + [/gdscript] + [csharp] + public override void _Ready() + { + var monitorValue = new Callable(this, nameof(GetMonitorValue)); + + // Adds monitor with name "MyName" to category "MyCategory". + Performance.AddCustomMonitor("MyCategory/MyMonitor", monitorValue); + // Adds monitor with name "MyName" to category "Custom". + // Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different ids so the code is valid. + Performance.AddCustomMonitor("MyMonitor", monitorValue); + + // Adds monitor with name "MyName" to category "Custom". + // Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different ids so the code is valid. + Performance.AddCustomMonitor("Custom/MyMonitor", monitorValue); + + // Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom". + Performance.AddCustomMonitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitorValue); + } + + public int GetMonitorValue() + { + return GD.Randi() % 25; + } + [/csharp] + [/codeblocks] The debugger calls the callable to get the value of custom monitor. The callable must return a number. Callables are called with arguments supplied in argument array. [b]Note:[/b] It throws an error if given id is already present. @@ -61,9 +100,14 @@ </argument> <description> Returns the value of one of the available monitors. You should provide one of the [enum Monitor] constants as the argument, like this: - [codeblock] - print(Performance.get_monitor(Performance.TIME_FPS)) # Prints the FPS to the console - [/codeblock] + [codeblocks] + [gdscript] + print(Performance.get_monitor(Performance.TIME_FPS)) # Prints the FPS to the console. + [/gdscript] + [csharp] + GD.Print(Performance.GetMonitor(Performance.Monitor.TimeFps)); // Prints the FPS to the console. + [/csharp] + [/codeblocks] </description> </method> <method name="get_monitor_modification_time"> diff --git a/doc/classes/PhysicsShapeQueryParameters2D.xml b/doc/classes/PhysicsShapeQueryParameters2D.xml index 93ca684b95..4d7fc61517 100644 --- a/doc/classes/PhysicsShapeQueryParameters2D.xml +++ b/doc/classes/PhysicsShapeQueryParameters2D.xml @@ -34,19 +34,34 @@ </member> <member name="shape_rid" type="RID" setter="set_shape_rid" getter="get_shape_rid"> The queried shape's [RID] that will be used for collision/intersection queries. Use this over [member shape] if you want to optimize for performance using the Servers API: - [codeblock] - var shape_rid = PhysicsServer2D.circle_shape_create() - var radius = 64 - PhysicsServer2D.shape_set_data(shape_rid, radius) + [codeblocks] + [gdscript] + var shape_rid = PhysicsServer2D.circle_shape_create() + var radius = 64 + PhysicsServer2D.shape_set_data(shape_rid, radius) - var params = PhysicsShapeQueryParameters2D.new() - params.shape_rid = shape_rid + var params = PhysicsShapeQueryParameters2D.new() + params.shape_rid = shape_rid - # Execute physics queries here... + # Execute physics queries here... - # Release the shape when done with physics queries. - PhysicsServer2D.free_rid(shape_rid) - [/codeblock] + # Release the shape when done with physics queries. + PhysicsServer2D.free_rid(shape_rid) + [/gdscript] + [csharp] + RID shapeRid = PhysicsServer2D.CircleShapeCreate(); + int radius = 64; + PhysicsServer2D.ShapeSetData(shapeRid, radius); + + var params = new PhysicsShapeQueryParameters2D(); + params.ShapeRid = shapeRid; + + // Execute physics queries here... + + // Release the shape when done with physics queries. + PhysicsServer2D.FreeRid(shapeRid); + [/csharp] + [/codeblocks] </member> <member name="transform" type="Transform2D" setter="set_transform" getter="get_transform" default="Transform2D( 1, 0, 0, 1, 0, 0 )"> The queried shape's transform matrix. diff --git a/doc/classes/PhysicsShapeQueryParameters3D.xml b/doc/classes/PhysicsShapeQueryParameters3D.xml index 167fb31bb3..4b43ea66fc 100644 --- a/doc/classes/PhysicsShapeQueryParameters3D.xml +++ b/doc/classes/PhysicsShapeQueryParameters3D.xml @@ -31,19 +31,34 @@ </member> <member name="shape_rid" type="RID" setter="set_shape_rid" getter="get_shape_rid"> The queried shape's [RID] that will be used for collision/intersection queries. Use this over [member shape] if you want to optimize for performance using the Servers API: - [codeblock] - var shape_rid = PhysicsServer3D.shape_create(PhysicsServer3D.SHAPE_SPHERE) - var radius = 2.0 - PhysicsServer3D.shape_set_data(shape_rid, radius) + [codeblocks] + [gdscript] + var shape_rid = PhysicsServer3D.shape_create(PhysicsServer3D.SHAPE_SPHERE) + var radius = 2.0 + PhysicsServer3D.shape_set_data(shape_rid, radius) - var params = PhysicsShapeQueryParameters3D.new() - params.shape_rid = shape_rid + var params = PhysicsShapeQueryParameters3D.new() + params.shape_rid = shape_rid - # Execute physics queries here... + # Execute physics queries here... - # Release the shape when done with physics queries. - PhysicsServer3D.free_rid(shape_rid) - [/codeblock] + # Release the shape when done with physics queries. + PhysicsServer3D.free_rid(shape_rid) + [/gdscript] + [csharp] + RID shapeRid = PhysicsServer3D.ShapeCreate(PhysicsServer3D.ShapeType.Sphere); + float radius = 2.0f; + PhysicsServer3D.ShapeSetData(shapeRid, radius); + + var params = new PhysicsShapeQueryParameters3D(); + params.ShapeRid = shapeRid; + + // Execute physics queries here... + + // Release the shape when done with physics queries. + PhysicsServer3D.FreeRid(shapeRid); + [/csharp] + [/codeblocks] </member> <member name="transform" type="Transform" setter="set_transform" getter="get_transform" default="Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )"> The queried shape's transform matrix. diff --git a/doc/classes/Popup.xml b/doc/classes/Popup.xml index 6f77f3371d..b8d8a55412 100644 --- a/doc/classes/Popup.xml +++ b/doc/classes/Popup.xml @@ -12,6 +12,8 @@ </methods> <members> <member name="borderless" type="bool" setter="set_flag" getter="get_flag" override="true" default="true" /> + <member name="close_on_parent_focus" type="bool" setter="set_close_on_parent_focus" getter="get_close_on_parent_focus" default="true"> + </member> <member name="transient" type="bool" setter="set_transient" getter="is_transient" override="true" default="true" /> <member name="unresizable" type="bool" setter="set_flag" getter="get_flag" override="true" default="true" /> <member name="visible" type="bool" setter="set_visible" getter="is_visible" override="true" default="false" /> diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml index 9e7f26ed4f..7e9bccc1d7 100644 --- a/doc/classes/PrimitiveMesh.xml +++ b/doc/classes/PrimitiveMesh.xml @@ -14,11 +14,18 @@ </return> <description> Returns mesh arrays used to constitute surface of [Mesh]. The result can be passed to [method ArrayMesh.add_surface_from_arrays] to create a new surface. For example: - [codeblock] - var c := CylinderMesh.new() - var arr_mesh := ArrayMesh.new() + [codeblocks] + [gdscript] + var c = CylinderMesh.new() + var arr_mesh = ArrayMesh.new() arr_mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, c.get_mesh_arrays()) - [/codeblock] + [/gdscript] + [csharp] + var c = new CylinderMesh(); + var arrMesh = new ArrayMesh(); + arrMesh.AddSurfaceFromArrays(Mesh.PrimitiveType.Triangles, c.GetMeshArrays()); + [/csharp] + [/codeblocks] </description> </method> </methods> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 7ca2dae4d7..96d71db383 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -25,7 +25,8 @@ - [code]type[/code]: [int] (see [enum Variant.Type]) - optionally [code]hint[/code]: [int] (see [enum PropertyHint]) and [code]hint_string[/code]: [String] [b]Example:[/b] - [codeblock] + [codeblocks] + [gdscript] ProjectSettings.set("category/property_name", 0) var property_info = { @@ -36,7 +37,21 @@ } ProjectSettings.add_property_info(property_info) - [/codeblock] + [/gdscript] + [csharp] + ProjectSettings.Singleton.Set("category/property_name", 0); + + var propertyInfo = new Godot.Collections.Dictionary + { + {"name", "category/propertyName"}, + {"type", Variant.Type.Int}, + {"hint", PropertyHint.Enum}, + {"hint_string", "one,two,three"}, + }; + + ProjectSettings.AddPropertyInfo(propertyInfo); + [/csharp] + [/codeblocks] </description> </method> <method name="clear"> @@ -65,9 +80,14 @@ <description> Returns the value of a setting. [b]Example:[/b] - [codeblock] + [codeblocks] + [gdscript] print(ProjectSettings.get_setting("application/config/name")) - [/codeblock] + [/gdscript] + [csharp] + GD.Print(ProjectSettings.GetSetting("application/config/name")); + [/csharp] + [/codeblocks] </description> </method> <method name="globalize_path" qualifiers="const"> @@ -178,9 +198,14 @@ <description> Sets the value of a setting. [b]Example:[/b] - [codeblock] + [codeblocks] + [gdscript] ProjectSettings.set_setting("application/config/name", "Example") - [/codeblock] + [/gdscript] + [csharp] + ProjectSettings.SetSetting("application/config/name", "Example"); + [/csharp] + [/codeblocks] </description> </method> </methods> @@ -858,7 +883,7 @@ Maximum number of warnings allowed to be sent from the debugger. Over this value, content is dropped. This helps not to stall the debugger connection. </member> <member name="network/limits/packet_peer_stream/max_buffer_po2" type="int" setter="" getter="" default="16"> - Default size of packet peer stream for deserializing Godot data. Over this size, data is dropped. + Default size of packet peer stream for deserializing Godot data (in bytes, specified as a power of two). The default value [code]16[/code] is equal to 65,536 bytes. Over this size, data is dropped. </member> <member name="network/limits/tcp/connect_timeout_seconds" type="int" setter="" getter="" default="30"> Timeout (in seconds) for connection attempts using TCP. @@ -895,18 +920,30 @@ <member name="physics/2d/default_gravity" type="int" setter="" getter="" default="98"> The default gravity strength in 2D. [b]Note:[/b] This property is only read when the project starts. To change the default gravity at runtime, use the following code sample: - [codeblock] + [codeblocks] + [gdscript] # Set the default gravity strength to 98. - PhysicsServer2D.area_set_param(get_viewport().find_world_2d().get_space(), PhysicsServer2D.AREA_PARAM_GRAVITY, 98) - [/codeblock] + PhysicsServer2D.area_set_param(get_viewport().find_world_2d().space, PhysicsServer2D.AREA_PARAM_GRAVITY, 98) + [/gdscript] + [csharp] + // Set the default gravity strength to 98. + PhysicsServer2D.AreaSetParam(GetViewport().FindWorld2d().Space, PhysicsServer2D.AreaParameter.Gravity, 98); + [/csharp] + [/codeblocks] </member> <member name="physics/2d/default_gravity_vector" type="Vector2" setter="" getter="" default="Vector2( 0, 1 )"> The default gravity direction in 2D. [b]Note:[/b] This property is only read when the project starts. To change the default gravity vector at runtime, use the following code sample: - [codeblock] + [codeblocks] + [gdscript] # Set the default gravity direction to `Vector2(0, 1)`. - PhysicsServer2D.area_set_param(get_viewport().find_world_2d().get_space(), PhysicsServer2D.AREA_PARAM_GRAVITY_VECTOR, Vector2(0, 1)) - [/codeblock] + PhysicsServer2D.area_set_param(get_viewport().find_world_2d().space, PhysicsServer2D.AREA_PARAM_GRAVITY_VECTOR, Vector2.DOWN) + [/gdscript] + [csharp] + // Set the default gravity direction to `Vector2(0, 1)`. + PhysicsServer2D.AreaSetParam(GetViewport().FindWorld2d().Space, PhysicsServer2D.AreaParameter.GravityVector, Vector2.Down) + [/csharp] + [/codeblocks] </member> <member name="physics/2d/default_linear_damp" type="float" setter="" getter="" default="0.1"> The default linear damp in 2D. @@ -942,18 +979,30 @@ <member name="physics/3d/default_gravity" type="float" setter="" getter="" default="9.8"> The default gravity strength in 3D. [b]Note:[/b] This property is only read when the project starts. To change the default gravity at runtime, use the following code sample: - [codeblock] + [codeblocks] + [gdscript] # Set the default gravity strength to 9.8. - PhysicsServer3D.area_set_param(get_viewport().find_world().get_space(), PhysicsServer3D.AREA_PARAM_GRAVITY, 9.8) - [/codeblock] + PhysicsServer3D.area_set_param(get_viewport().find_world().space, PhysicsServer3D.AREA_PARAM_GRAVITY, 9.8) + [/gdscript] + [csharp] + // Set the default gravity strength to 9.8. + PhysicsServer3D.AreaSetParam(GetViewport().FindWorld().Space, PhysicsServer3D.AreaParameter.Gravity, 9.8); + [/csharp] + [/codeblocks] </member> <member name="physics/3d/default_gravity_vector" type="Vector3" setter="" getter="" default="Vector3( 0, -1, 0 )"> The default gravity direction in 3D. [b]Note:[/b] This property is only read when the project starts. To change the default gravity vector at runtime, use the following code sample: - [codeblock] + [codeblocks] + [gdscript] # Set the default gravity direction to `Vector3(0, -1, 0)`. - PhysicsServer3D.area_set_param(get_viewport().find_world().get_space(), PhysicsServer3D.AREA_PARAM_GRAVITY_VECTOR, Vector3(0, -1, 0)) - [/codeblock] + PhysicsServer3D.area_set_param(get_viewport().find_world().get_space(), PhysicsServer3D.AREA_PARAM_GRAVITY_VECTOR, Vector3.DOWN) + [/gdscript] + [csharp] + // Set the default gravity direction to `Vector3(0, -1, 0)`. + PhysicsServer3D.AreaSetParam(GetViewport().FindWorld().Space, PhysicsServer3D.AreaParameter.GravityVector, Vector3.Down) + [/csharp] + [/codeblocks] </member> <member name="physics/3d/default_linear_damp" type="float" setter="" getter="" default="0.1"> The default linear damp in 3D. diff --git a/doc/classes/Reference.xml b/doc/classes/Reference.xml index 9c3d1d5d9d..44ee6fbda1 100644 --- a/doc/classes/Reference.xml +++ b/doc/classes/Reference.xml @@ -7,6 +7,7 @@ Base class for any object that keeps a reference count. [Resource] and many other helper objects inherit this class. Unlike [Object]s, References keep an internal reference counter so that they are automatically released when no longer in use, and only then. References therefore do not need to be freed manually with [method Object.free]. In the vast majority of use cases, instantiating and using [Reference]-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#, references will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free references that are no longer in use. This means that unused references will linger on for a while before being removed. </description> <tutorials> <link title="When and how to avoid using nodes for everything">https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html</link> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 5830a8452c..22a9925d4b 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -3365,7 +3365,8 @@ Objects are displayed with only light information. </constant> <constant name="VIEWPORT_DEBUG_DRAW_OVERDRAW" value="3" enum="ViewportDebugDraw"> - Objects are displayed semi-transparent with additive blending so you can see where they are drawing over top of one another. A higher overdraw means you are wasting performance on drawing pixels that are being hidden behind others. + Objects are displayed semi-transparent with additive blending so you can see where they are drawing over top of one another. A higher overdraw (represented by brighter colors) means you are wasting performance on drawing pixels that are being hidden behind others. + [b]Note:[/b] When using this debug draw mode, custom shaders will be ignored. This means vertex displacement won't be visible anymore. </constant> <constant name="VIEWPORT_DEBUG_DRAW_WIREFRAME" value="4" enum="ViewportDebugDraw"> Debug draw draws objects in wireframe. diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index e79a2e0ea9..1ce2c376dd 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -5,6 +5,7 @@ </brief_description> <description> Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Unlike [Object]s, they are reference-counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a [Node], which is not reference-counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource. + [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. </description> <tutorials> <link title="Resources">https://docs.godotengine.org/en/latest/getting_started/step_by_step/resources.html</link> diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml index 4ea457047f..a95ce6c663 100644 --- a/doc/classes/SceneTree.xml +++ b/doc/classes/SceneTree.xml @@ -181,7 +181,7 @@ <argument index="0" name="exit_code" type="int" default="-1"> </argument> <description> - Quits the application. A process [code]exit_code[/code] can optionally be passed as an argument. If this argument is [code]0[/code] or greater, it will override the [member OS.exit_code] defined before quitting the application. + Quits the application at the end of the current iteration. A process [code]exit_code[/code] can optionally be passed as an argument. If this argument is [code]0[/code] or greater, it will override the [member OS.exit_code] defined before quitting the application. </description> </method> <method name="reload_current_scene"> diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index 53d706db2d..168cc8a1c3 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -270,7 +270,7 @@ <return type="String"> </return> <description> - Returns a [String] text with the word under the mouse cursor location. + Returns a [String] text with the word under the caret (text cursor) location. </description> </method> <method name="insert_text_at_cursor"> diff --git a/doc/classes/Texture2D.xml b/doc/classes/Texture2D.xml index ff8b439a3d..2270b95c63 100644 --- a/doc/classes/Texture2D.xml +++ b/doc/classes/Texture2D.xml @@ -7,6 +7,7 @@ A texture works by registering an image in the video hardware, which then can be used in 3D models or 2D [Sprite2D] or GUI [Control]. Textures are often created by loading them from a file. See [method @GDScript.load]. [Texture2D] is a base for other resources. It cannot be used directly. + [b]Note:[/b] The maximum texture size is 16384×16384 pixels due to graphics hardware limitations. Larger textures may fail to import. </description> <tutorials> </tutorials> diff --git a/doc/classes/Theme.xml b/doc/classes/Theme.xml index 2824159f0e..783614c4af 100644 --- a/doc/classes/Theme.xml +++ b/doc/classes/Theme.xml @@ -23,10 +23,10 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Clears the [Color] at [code]name[/code] if the theme has [code]type[/code]. + Clears the [Color] at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="clear_constant"> @@ -34,10 +34,10 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Clears the constant at [code]name[/code] if the theme has [code]type[/code]. + Clears the constant at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="clear_font"> @@ -45,10 +45,10 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Clears the [Font] at [code]name[/code] if the theme has [code]type[/code]. + Clears the [Font] at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="clear_icon"> @@ -56,10 +56,10 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Clears the icon at [code]name[/code] if the theme has [code]type[/code]. + Clears the icon at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="clear_stylebox"> @@ -67,10 +67,10 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Clears [StyleBox] at [code]name[/code] if the theme has [code]type[/code]. + Clears [StyleBox] at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="copy_default_theme"> @@ -94,19 +94,19 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns the [Color] at [code]name[/code] if the theme has [code]type[/code]. + Returns the [Color] at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="get_color_list" qualifiers="const"> <return type="PackedStringArray"> </return> - <argument index="0" name="type" type="String"> + <argument index="0" name="node_type" type="String"> </argument> <description> - Returns all the [Color]s as a [PackedStringArray] filled with each [Color]'s name, for use in [method get_color], if the theme has [code]type[/code]. + Returns all the [Color]s as a [PackedStringArray] filled with each [Color]'s name, for use in [method get_color], if the theme has [code]node_type[/code]. </description> </method> <method name="get_constant" qualifiers="const"> @@ -114,19 +114,19 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns the constant at [code]name[/code] if the theme has [code]type[/code]. + Returns the constant at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="get_constant_list" qualifiers="const"> <return type="PackedStringArray"> </return> - <argument index="0" name="type" type="String"> + <argument index="0" name="node_type" type="String"> </argument> <description> - Returns all the constants as a [PackedStringArray] filled with each constant's name, for use in [method get_constant], if the theme has [code]type[/code]. + Returns all the constants as a [PackedStringArray] filled with each constant's name, for use in [method get_constant], if the theme has [code]node_type[/code]. </description> </method> <method name="get_font" qualifiers="const"> @@ -134,19 +134,19 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns the [Font] at [code]name[/code] if the theme has [code]type[/code]. + Returns the [Font] at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="get_font_list" qualifiers="const"> <return type="PackedStringArray"> </return> - <argument index="0" name="type" type="String"> + <argument index="0" name="node_type" type="String"> </argument> <description> - Returns all the [Font]s as a [PackedStringArray] filled with each [Font]'s name, for use in [method get_font], if the theme has [code]type[/code]. + Returns all the [Font]s as a [PackedStringArray] filled with each [Font]'s name, for use in [method get_font], if the theme has [code]node_type[/code]. </description> </method> <method name="get_icon" qualifiers="const"> @@ -154,19 +154,19 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns the icon [Texture2D] at [code]name[/code] if the theme has [code]type[/code]. + Returns the icon [Texture2D] at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="get_icon_list" qualifiers="const"> <return type="PackedStringArray"> </return> - <argument index="0" name="type" type="String"> + <argument index="0" name="node_type" type="String"> </argument> <description> - Returns all the icons as a [PackedStringArray] filled with each [Texture2D]'s name, for use in [method get_icon], if the theme has [code]type[/code]. + Returns all the icons as a [PackedStringArray] filled with each [Texture2D]'s name, for use in [method get_icon], if the theme has [code]node_type[/code]. </description> </method> <method name="get_stylebox" qualifiers="const"> @@ -174,35 +174,35 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns the icon [StyleBox] at [code]name[/code] if the theme has [code]type[/code]. + Returns the icon [StyleBox] at [code]name[/code] if the theme has [code]node_type[/code]. </description> </method> <method name="get_stylebox_list" qualifiers="const"> <return type="PackedStringArray"> </return> - <argument index="0" name="type" type="String"> + <argument index="0" name="node_type" type="String"> </argument> <description> - Returns all the [StyleBox]s as a [PackedStringArray] filled with each [StyleBox]'s name, for use in [method get_stylebox], if the theme has [code]type[/code]. + Returns all the [StyleBox]s as a [PackedStringArray] filled with each [StyleBox]'s name, for use in [method get_stylebox], if the theme has [code]node_type[/code]. </description> </method> <method name="get_stylebox_types" qualifiers="const"> <return type="PackedStringArray"> </return> <description> - Returns all the [StyleBox] types as a [PackedStringArray] filled with each [StyleBox]'s type, for use in [method get_stylebox] and/or [method get_stylebox_list], if the theme has [code]type[/code]. + Returns all the [StyleBox] types as a [PackedStringArray] filled with each [StyleBox]'s type, for use in [method get_stylebox] and/or [method get_stylebox_list], if the theme has [code]node_type[/code]. </description> </method> <method name="get_type_list" qualifiers="const"> <return type="PackedStringArray"> </return> - <argument index="0" name="type" type="String"> + <argument index="0" name="node_type" type="String"> </argument> <description> - Returns all the types in [code]type[/code] as a [PackedStringArray] for use in any of the [code]get_*[/code] functions, if the theme has [code]type[/code]. + Returns all the types in [code]node_type[/code] as a [PackedStringArray] for use in any of the [code]get_*[/code] functions, if the theme has [code]node_type[/code]. </description> </method> <method name="has_color" qualifiers="const"> @@ -210,11 +210,11 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns [code]true[/code] if [Color] with [code]name[/code] is in [code]type[/code]. - Returns [code]false[/code] if the theme does not have [code]type[/code]. + Returns [code]true[/code] if [Color] with [code]name[/code] is in [code]node_type[/code]. + Returns [code]false[/code] if the theme does not have [code]node_type[/code]. </description> </method> <method name="has_constant" qualifiers="const"> @@ -222,11 +222,11 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns [code]true[/code] if constant with [code]name[/code] is in [code]type[/code]. - Returns [code]false[/code] if the theme does not have [code]type[/code]. + Returns [code]true[/code] if constant with [code]name[/code] is in [code]node_type[/code]. + Returns [code]false[/code] if the theme does not have [code]node_type[/code]. </description> </method> <method name="has_font" qualifiers="const"> @@ -234,11 +234,11 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns [code]true[/code] if [Font] with [code]name[/code] is in [code]type[/code]. - Returns [code]false[/code] if the theme does not have [code]type[/code]. + Returns [code]true[/code] if [Font] with [code]name[/code] is in [code]node_type[/code]. + Returns [code]false[/code] if the theme does not have [code]node_type[/code]. </description> </method> <method name="has_icon" qualifiers="const"> @@ -246,11 +246,11 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns [code]true[/code] if icon [Texture2D] with [code]name[/code] is in [code]type[/code]. - Returns [code]false[/code] if the theme does not have [code]type[/code]. + Returns [code]true[/code] if icon [Texture2D] with [code]name[/code] is in [code]node_type[/code]. + Returns [code]false[/code] if the theme does not have [code]node_type[/code]. </description> </method> <method name="has_stylebox" qualifiers="const"> @@ -258,11 +258,11 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <description> - Returns [code]true[/code] if [StyleBox] with [code]name[/code] is in [code]type[/code]. - Returns [code]false[/code] if the theme does not have [code]type[/code]. + Returns [code]true[/code] if [StyleBox] with [code]name[/code] is in [code]node_type[/code]. + Returns [code]false[/code] if the theme does not have [code]node_type[/code]. </description> </method> <method name="set_color"> @@ -270,13 +270,13 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <argument index="2" name="color" type="Color"> </argument> <description> - Sets the theme's [Color] to [code]color[/code] at [code]name[/code] in [code]type[/code]. - Does nothing if the theme does not have [code]type[/code]. + Sets the theme's [Color] to [code]color[/code] at [code]name[/code] in [code]node_type[/code]. + Does nothing if the theme does not have [code]node_type[/code]. </description> </method> <method name="set_constant"> @@ -284,13 +284,13 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <argument index="2" name="constant" type="int"> </argument> <description> - Sets the theme's constant to [code]constant[/code] at [code]name[/code] in [code]type[/code]. - Does nothing if the theme does not have [code]type[/code]. + Sets the theme's constant to [code]constant[/code] at [code]name[/code] in [code]node_type[/code]. + Does nothing if the theme does not have [code]node_type[/code]. </description> </method> <method name="set_font"> @@ -298,13 +298,13 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <argument index="2" name="font" type="Font"> </argument> <description> - Sets the theme's [Font] to [code]font[/code] at [code]name[/code] in [code]type[/code]. - Does nothing if the theme does not have [code]type[/code]. + Sets the theme's [Font] to [code]font[/code] at [code]name[/code] in [code]node_type[/code]. + Does nothing if the theme does not have [code]node_type[/code]. </description> </method> <method name="set_icon"> @@ -312,13 +312,13 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <argument index="2" name="texture" type="Texture2D"> </argument> <description> - Sets the theme's icon [Texture2D] to [code]texture[/code] at [code]name[/code] in [code]type[/code]. - Does nothing if the theme does not have [code]type[/code]. + Sets the theme's icon [Texture2D] to [code]texture[/code] at [code]name[/code] in [code]node_type[/code]. + Does nothing if the theme does not have [code]node_type[/code]. </description> </method> <method name="set_stylebox"> @@ -326,13 +326,13 @@ </return> <argument index="0" name="name" type="StringName"> </argument> - <argument index="1" name="type" type="StringName"> + <argument index="1" name="node_type" type="StringName"> </argument> <argument index="2" name="texture" type="StyleBox"> </argument> <description> - Sets theme's [StyleBox] to [code]stylebox[/code] at [code]name[/code] in [code]type[/code]. - Does nothing if the theme does not have [code]type[/code]. + Sets theme's [StyleBox] to [code]stylebox[/code] at [code]name[/code] in [code]node_type[/code]. + Does nothing if the theme does not have [code]node_type[/code]. </description> </method> </methods> diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index 0b2fb80480..73575b4309 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -106,14 +106,21 @@ <return type="TreeItem"> </return> <description> - Returns the currently edited item. This is only available for custom cell mode. + Returns the currently edited item. Can be used with [signal item_edited] to get the item that was modified. + [codeblock] + func _ready(): + $Tree.item_edited.connect(on_Tree_item_edited) + + func on_Tree_item_edited(): + print($Tree.get_edited()) # This item just got edited (e.g. checked). + [/codeblock] </description> </method> <method name="get_edited_column" qualifiers="const"> <return type="int"> </return> <description> - Returns the column for the currently edited item. This is only available for custom cell mode. + Returns the column for the currently edited item. </description> </method> <method name="get_item_area_rect" qualifiers="const"> diff --git a/doc/classes/World2D.xml b/doc/classes/World2D.xml index b0bfd7f418..25033cdb09 100644 --- a/doc/classes/World2D.xml +++ b/doc/classes/World2D.xml @@ -16,7 +16,7 @@ The [RID] of this world's canvas resource. Used by the [RenderingServer] for 2D drawing. </member> <member name="direct_space_state" type="PhysicsDirectSpaceState2D" setter="" getter="get_direct_space_state"> - Direct access to the world's physics 2D space state. Used for querying current and potential collisions. Must only be accessed from the main thread within [code]_physics_process(delta)[/code]. + Direct access to the world's physics 2D space state. Used for querying current and potential collisions. When using multi-threaded physics, access is limited to [code]_physics_process(delta)[/code] in the main thread. </member> <member name="space" type="RID" setter="" getter="get_space"> The [RID] of this world's physics space resource. Used by the [PhysicsServer2D] for 2D physics, treating it as both a space and an area. diff --git a/doc/classes/World3D.xml b/doc/classes/World3D.xml index d804485d4e..fe92077432 100644 --- a/doc/classes/World3D.xml +++ b/doc/classes/World3D.xml @@ -15,7 +15,7 @@ <member name="camera_effects" type="CameraEffects" setter="set_camera_effects" getter="get_camera_effects"> </member> <member name="direct_space_state" type="PhysicsDirectSpaceState3D" setter="" getter="get_direct_space_state"> - Direct access to the world's physics 3D space state. Used for querying current and potential collisions. Must only be accessed from within [code]_physics_process(delta)[/code]. + Direct access to the world's physics 3D space state. Used for querying current and potential collisions. </member> <member name="environment" type="Environment" setter="set_environment" getter="get_environment"> The World3D's [Environment]. diff --git a/doc/classes/int.xml b/doc/classes/int.xml index 5ac9f8405a..b0d0a4bd7b 100644 --- a/doc/classes/int.xml +++ b/doc/classes/int.xml @@ -7,18 +7,34 @@ Signed 64-bit integer type. It can take values in the interval [code][-2^63, 2^63 - 1][/code], i.e. [code][-9223372036854775808, 9223372036854775807][/code]. Exceeding those bounds will wrap around. [int] is a [Variant] type, and will thus be used when assigning an integer value to a [Variant]. It can also be enforced with the [code]: int[/code] type hint. - [codeblock] + [codeblocks] + [gdscript] var my_variant = 0 # int, value 0. my_variant += 4.2 # float, value 4.2. var my_int: int = 1 # int, value 1. my_int = 4.2 # int, value 4, the right value is implicitly cast to int. my_int = int("6.7") # int, value 6, the String is explicitly cast with int. - var max_int = 9223372036854775807 print(max_int) # 9223372036854775807, OK. max_int += 1 print(max_int) # -9223372036854775808, we overflowed and wrapped around. - [/codeblock] + [/gdscript] + [csharp] + int myInt = (int)"6.7".ToFloat(); // int, value 6, the String is explicitly cast with int. + // We have to use `long` here, because GDSript's `int` + // is 64 bits long while C#'s `int` is only 32 bits. + long maxInt = 9223372036854775807; + GD.Print(maxInt); // 9223372036854775807, OK. + maxInt++; + GD.Print(maxInt); // -9223372036854775808, we overflowed and wrapped around. + + // Alternatively, if we used C#'s 32-bit `int` type, the maximum value is much smaller: + int halfInt = 2147483647; + GD.Print(halfInt); // 2147483647, OK. + halfInt++; + GD.Print(halfInt); // -2147483648, we overflowed and wrapped around. + [/csharp] + [/codeblocks] </description> <tutorials> </tutorials> |