diff options
Diffstat (limited to 'modules/gdscript/doc_classes/@GDScript.xml')
| -rw-r--r-- | modules/gdscript/doc_classes/@GDScript.xml | 148 |
1 files changed, 58 insertions, 90 deletions
diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml index f04cb4b4c3..9e40a69712 100644 --- a/modules/gdscript/doc_classes/@GDScript.xml +++ b/modules/gdscript/doc_classes/@GDScript.xml @@ -52,7 +52,7 @@ <argument index="0" name="s" type="float"> </argument> <description> - Returns the absolute value of parameter [code]s[/code] (i.e. unsigned value, works for integer and float). + Returns the absolute value of parameter [code]s[/code] (i.e. positive value). [codeblock] # a is 1 a = abs(-1) @@ -112,7 +112,7 @@ </argument> <description> Returns the arc tangent of [code]s[/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 always want an exact angle. + 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] @@ -127,6 +127,7 @@ </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] @@ -161,7 +162,7 @@ <argument index="0" name="s" type="float"> </argument> <description> - Rounds [code]s[/code] upward, returning the smallest integral value that is not less than [code]s[/code]. + Rounds [code]s[/code] upward (towards positive infinity), returning the smallest whole number that is not less than [code]s[/code]. [codeblock] i = ceil(1.45) # i is 2 i = ceil(1.001) # i is 2 @@ -283,7 +284,7 @@ <argument index="0" name="deg" type="float"> </argument> <description> - Returns degrees converted to radians. + Converts an angle expressed in degrees to radians. [codeblock] # r is 3.141593 r = deg2rad(180) @@ -307,7 +308,7 @@ <argument index="1" name="curve" type="float"> </argument> <description> - Easing function, based on exponent. 0 is constant, 1 is linear, 0 to 1 is ease-in, 1+ is ease out. Negative values are in-out/out in. + 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"> @@ -317,7 +318,7 @@ </argument> <description> The natural exponential function. It raises the mathematical constant [b]e[/b] to the power of [code]s[/code] and returns it. - [b]e[/b] has an approximate value of 2.71828. + [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 @@ -330,7 +331,7 @@ <argument index="0" name="s" type="float"> </argument> <description> - Rounds [code]s[/code] to the closest smaller integer and returns it. + Rounds [code]s[/code] downward (towards negative infinity), returning the largest whole number that is not more than [code]s[/code]. [codeblock] # a is 2.0 a = floor(2.99) @@ -504,6 +505,8 @@ </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"> @@ -530,7 +533,7 @@ <argument index="0" name="s" type="float"> </argument> <description> - Returns whether [code]s[/code] is a NaN (Not-A-Number) value. + Returns whether [code]s[/code] is a NaN ("Not a Number" or invalid) value. </description> </method> <method name="is_zero_approx"> @@ -540,6 +543,7 @@ </argument> <description> Returns [code]true[/code] if [code]s[/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="len"> @@ -639,6 +643,7 @@ [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"> @@ -684,7 +689,9 @@ 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> @@ -694,12 +701,17 @@ <argument index="0" name="value" type="int"> </argument> <description> - Returns the nearest larger power of 2 for integer [code]value[/code]. + 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="ord"> @@ -723,16 +735,17 @@ <argument index="0" name="json" type="String"> </argument> <description> - Parse JSON text to a Variant (use [method typeof] to check if it is what you expect). - Be aware that the JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to [float] types. - Note that 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: + Parse JSON text to a Variant. (Use [method typeof] to check if the Variant's type is what you expect.) + [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] - p = parse_json('["a", "b", "c"]') - if typeof(p) == TYPE_ARRAY: - print(p[0]) # Prints a + var p = JSON.parse('["hello", "world", "!"]') + if typeof(p.result) == TYPE_ARRAY: + print(p.result[0]) # Prints "hello" else: - print("unexpected results") + push_error("Unexpected results.") [/codeblock] + See also [JSON] for an alternative way to parse JSON text. </description> </method> <method name="polar2cartesian"> @@ -907,7 +920,7 @@ <argument index="0" name="rad" type="float"> </argument> <description> - Converts from radians to degrees. + Converts an angle expressed in radians to degrees. [codeblock] rad2deg(0.523599) # Returns 30 [/codeblock] @@ -1026,7 +1039,7 @@ <argument index="0" name="s" type="float"> </argument> <description> - Returns the integral value that is nearest to [code]s[/code], with halfway cases rounded away from zero. + Rounds [code]s[/code] to the nearest whole number, with halfway cases rounded away from zero. [codeblock] round(2.6) # Returns 3 [/codeblock] @@ -1091,12 +1104,15 @@ </argument> <argument index="1" name="to" type="float"> </argument> - <argument index="2" name="weight" type="float"> + <argument index="2" name="s" type="float"> </argument> <description> - Returns a number smoothly interpolated between the [code]from[/code] and [code]to[/code], based on the [code]weight[/code]. Similar to [method lerp], but interpolates faster at the beginning and slower at the end. + Returns the result of smoothly interpolating the value of [code]s[/code] between [code]0[/code] and [code]1[/code], based on the where [code]s[/code] lies with respect to the edges [code]from[/code] and [code]to[/code]. + The return value is [code]0[/code] if [code]s <= from[/code], and [code]1[/code] if [code]s >= to[/code]. If [code]s[/code] lies between [code]from[/code] and [code]to[/code], the returned value follows an S-shaped curve that maps [code]s[/code] between [code]0[/code] and [code]1[/code]. + This S-shaped curve is the cubic Hermite interpolator, given by [code]f(s) = 3*s^2 - 2*s^3[/code]. [codeblock] - smoothstep(0, 2, 0.5) # Returns 0.15 + 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] @@ -1108,10 +1124,11 @@ <argument index="0" name="s" type="float"> </argument> <description> - Returns the square root of [code]s[/code]. + Returns the square root of [code]s[/code], where [code]s[/code] is a non-negative number. [codeblock] sqrt(9) # Returns 3 [/codeblock] + [b]Note:[/b]Negative values of [code]s[/code] return NaN. If you need negative inputs, use [code]System.Numerics.Complex[/code] in C#. </description> </method> <method name="step_decimals"> @@ -1204,12 +1221,16 @@ <argument index="0" name="var" type="Variant"> </argument> <description> - Converts a Variant [code]var[/code] to JSON text and return the result. Useful for serializing data to store or send over the network. + Converts a [Variant] [code]var[/code] to JSON text and return the result. Useful for serializing data to store or send over the network. [codeblock] + # Both numbers below are integers. a = { "a": 1, "b": 2 } b = to_json(a) print(b) # {"a":1, "b":2} + # Both numbers above are floats, even if they display without any decimal places. [/codeblock] + [b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, converting a [Variant] to JSON text will convert all numerical values to [float] types. + See also [JSON] for an alternative way to convert a [Variant] to JSON text. </description> </method> <method name="type_exists"> @@ -1252,9 +1273,9 @@ j = to_json([1, 2, 3]) v = validate_json(j) if not v: - print("valid") + print("Valid JSON.") else: - prints("invalid", v) + push_error("Invalid JSON: " + v) [/codeblock] </description> </method> @@ -1312,27 +1333,19 @@ Wraps float [code]value[/code] between [code]min[/code] and [code]max[/code]. Usable for creating loop-alike behavior or infinite surfaces. [codeblock] - # a is 0.5 - a = wrapf(10.5, 0.0, 10.0) - [/codeblock] - [codeblock] - # a is 9.5 - a = wrapf(-0.5, 0.0, 10.0) - [/codeblock] - [codeblock] - # Infinite loop between 0.0 and 0.99 - f = wrapf(f + 0.1, 0.0, 1.0) + # 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] - [b]Note:[/b] If you just want to wrap between 0.0 and [code]n[/code] (where [code]n[/code] is a positive floating-point value), it is better for performance to use the [method fmod] method like [code]fmod(number, n)[/code]. - [code]wrapf[/code] is more flexible than using the [method fmod] approach by giving the user a simple control over the minimum value. It also fully supports negative numbers, e.g. [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"> @@ -1348,75 +1361,30 @@ Wraps integer [code]value[/code] between [code]min[/code] and [code]max[/code]. Usable for creating loop-alike behavior or infinite surfaces. [codeblock] - # a is 0 - a = wrapi(10, 0, 10) + # Infinite loop between 5 and 9 + frame = wrapi(frame + 1, 5, 10) [/codeblock] [codeblock] - # a is 9 - a = wrapi(-1, 0, 10) - [/codeblock] - [codeblock] - # Infinite loop between 0 and 9 - frame = wrapi(frame + 1, 0, 10) - [/codeblock] - [b]Note:[/b] If you just want to wrap between 0 and [code]n[/code] (where [code]n[/code] is a positive integer value), it is better for performance to use the modulo operator like [code]number % n[/code]. - [code]wrapi[/code] is more flexible than using the modulo approach by giving the user a simple control over the minimum value. It also fully supports negative numbers, e.g. - [codeblock] # result is -2 var result = wrapi(-6, -5, -1) [/codeblock] - </description> - </method> - <method name="yield"> - <return type="GDScriptFunctionState"> - </return> - <argument index="0" name="object" type="Object" default="null"> - </argument> - <argument index="1" name="signal" type="String" default=""""> - </argument> - <description> - Stops the function execution and returns the current suspended state to the calling function. - From the caller, call [method GDScriptFunctionState.resume] on the state to resume execution. This invalidates the state. Within the resumed function, [code]yield()[/code] returns whatever was passed to the [code]resume()[/code] function call. - If passed an object and a signal, the execution is resumed when the object emits the given signal. In this case, [code]yield()[/code] returns the argument passed to [code]emit_signal()[/code] if the signal takes only one argument, or an array containing all the arguments passed to [code]emit_signal()[/code] if the signal takes multiple arguments. - You can also use [code]yield[/code] to wait for a function to finish: - [codeblock] - func _ready(): - yield(countdown(), "completed") # waiting for the countdown() function to complete - print('Ready') - - func countdown(): - yield(get_tree(), "idle_frame") # returns a GDScriptFunctionState object to _ready() - print(3) - yield(get_tree().create_timer(1.0), "timeout") - print(2) - yield(get_tree().create_timer(1.0), "timeout") - print(1) - yield(get_tree().create_timer(1.0), "timeout") - - # prints: - # 3 - # 2 - # 1 - # Ready - [/codeblock] - When yielding on a function, the [code]completed[/code] signal will be emitted automatically when the function returns. It can, therefore, be used as the [code]signal[/code] parameter of the [code]yield[/code] method to resume. - In order to yield on a function, the resulting function should also return a [code]GDScriptFunctionState[/code]. Notice [code]yield(get_tree(), "idle_frame")[/code] from the above example. + [b]Note:[/b] If [code]min[/code] is [code]0[/code], this is equivalent to [method posmod], so prefer using that instead. + [code]wrapi[/code] is more flexible than using the [method posmod] approach by giving the user control over the minimum value. </description> </method> </methods> <constants> <constant name="PI" value="3.141593"> - Constant that represents how many times the diameter of a circle fits around its perimeter. + Constant that represents how many times the diameter of a circle fits around its perimeter. This is equivalent to [code]TAU / 2[/code]. </constant> <constant name="TAU" value="6.283185"> - The circle constant, the circumference of the unit circle. + The circle constant, the circumference of the unit circle in radians. </constant> <constant name="INF" value="inf"> - A positive infinity. (For negative infinity, use -INF). + Positive infinity. For negative infinity, use -INF. </constant> <constant name="NAN" value="nan"> - Macro constant that expands to an expression of type float that represents a NaN. - The NaN values are used to identify undefined or non-representable values for floating-point elements, such as the square root of negative numbers or the result of 0/0. + "Not a Number", an invalid value. [code]NaN[/code] has special properties, including that it is not equal to itself. It is output by some invalid operations, such as dividing zero by zero. </constant> </constants> </class> |