From 8632408dbd50223256a140940a5f02fb040a79da Mon Sep 17 00:00:00 2001 From: William Taylor Date: Tue, 12 Sep 2017 06:00:29 -0700 Subject: =?UTF-8?q?Changed/Added=20descriptions=20in=20@GDScript.=20Added?= =?UTF-8?q?=20examples.=20Fixed=20return=20types=20of=20two=20=E2=80=A6=20?= =?UTF-8?q?(#11146)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Doc: Improved descriptions in GDScript docs Added examples and fixed return types of two methods. --- doc/base/classes.xml | 277 +++++++++++++++++++++++++++++++++----- modules/gdscript/gd_functions.cpp | 4 +- 2 files changed, 245 insertions(+), 36 deletions(-) diff --git a/doc/base/classes.xml b/doc/base/classes.xml index e3af2ff8ee..91c1c72ff5 100644 --- a/doc/base/classes.xml +++ b/doc/base/classes.xml @@ -20,7 +20,14 @@ - Make a color from red, green, blue and alpha. Arguments can range from 0 to 255. + Returns a 32 bit color with red, green, blue and alpha channels. Each channel has 8bits of information ranging from 0 to 255. + 'r8' red channel + 'g8' green channel + 'b8' blue channel + 'a8' alpha channel + [codeblock] + red = Color8(255, 0, 0) + [/codeblock] @@ -31,7 +38,10 @@ - Make a color from color name (color_names.inc) and alpha ranging from 0 to 1. + Returns color 'name' with alpha ranging from 0 to 1. Note: 'name' is defined in color_names.inc. + [codeblock] + red = ColorN('red') + [/codeblock] @@ -40,7 +50,11 @@ - Returns the absolute value of parameter s (i.e. unsigned value, works for integer and float). + Returns the absolute value of parameter 's' (i.e. unsigned value, works for integer and float). + [codeblock] + # a is 1 + a = abs(-1) + [/codeblock] @@ -49,7 +63,11 @@ - Returns the principal value of the arc cosine of s, expressed in radians. In trigonometrics, arc cosine is the inverse operation of cosine. + Returns the arc cosine of 's' in radians. Use to get the angle of cosine 's'. + [codeblock] + # c is 0.523599 or 30 degrees if converted with rad2deg(s) + c = acos(0.866025) + [/codeblock] @@ -58,7 +76,11 @@ - Returns the principal value of the arc sine of s, expressed in radians. In trigonometrics, arc sine is the inverse operation of sine. + Returns the arc sine of 's' in radians. Use to get the angle of sine 's'. + [codeblock] + # s is 0.523599 or 30 degrees if converted with rad2deg(s) + s = asin(0.5) + [/codeblock] @@ -67,7 +89,18 @@ - Assert that the condition is true. If the condition is false, generates an error. + Assert that the condition is true. If the condition is false a fatal error is generated and the program is halted. + Useful for debugging to make sure a value is always true. + [codeblock] + # Speed should always be between 0 and 20 + speed = -10 + # Is true + assert(speed < 20) + # Is false and program stops + assert(speed >= 0) + # or simply + assert(speed >= 0 && speed < 20) + [/codeblock] @@ -76,7 +109,11 @@ - Returns the principal value of the arc tangent of s, expressed in radians. In trigonometrics, arc tangent is the inverse operation of tangent. Notice that because of the sign ambiguity, the function cannot determine with certainty in which quadrant the angle falls only by its tangent value. See [method atan2] for an alternative that takes a fractional argument instead. + Returns the arc tangent of 's' in radians. Use to get the angle of tangent 's'. Notice that because of the sign ambiguity, the function cannot determine with certainty in which quadrant the angle falls only by its tangent value. See [method atan2] for an alternative that takes a fractional argument instead. + [codeblock] + # a is 0.463648 + a = atan(0.5) + [/codeblock] @@ -87,7 +124,11 @@ - Returns the principal value of the arc tangent of y/x, expressed in radians. To compute the value, the function takes into account the sign of both arguments in order to determine the quadrant. + Returns the arc tangent of y/x in radians. Use to get the angle of tangent y/x. To compute the value, the function takes into account the sign of both arguments in order to determine the quadrant. + [codeblock] + # a is 3.141593 + a = atan(0,-1) + [/codeblock] @@ -105,7 +146,13 @@ - Rounds s upward, returning the smallest integral value that is not less than s. + Rounds 's' upward, returning the smallest integral value that is not less than 's'. + [codeblock] + # i is 2 + i = ceil(1.45) + # i is 2 + i = ceil(1.001) + [/codeblock] @@ -115,6 +162,12 @@ Returns a character as String of the given ASCII code. + [codeblock] + # a is 'A' + a = char(65) + # a is 'a' + a = char(65+32) + [/codeblock] @@ -127,7 +180,16 @@ - Clamps a value between a minimum and maximum value. + Clamp 'val' and return a value not less than 'min' and not more than 'max'. + [codeblock] + speed = 1000 + # a is 20 + a = clamp(speed, 1, 20) + + speed = -10 + # a is 1 + a = clamp(speed, 1, 20) + [/codeblock] @@ -139,6 +201,15 @@ Convert from a type to another in the best way possible. The "type" parameter uses the enum TYPE_* in [@Global Scope]. + [codeblock] + a = Vector2(1, 0) + # prints 1 + print(a.length()) + a = convert(a, TYPE_STRING) + # prints 6 + # (1, 0) is 6 characters + print(a.length()) + [/codeblock] @@ -147,7 +218,12 @@ - Returns the cosine of an angle of s radians. + Returns the cosine of angle 's' in radians. + [codeblock] + # prints 1 and -1 + print(cos(PI*2)) + print(cos(PI)) + [/codeblock] @@ -156,7 +232,11 @@ - Returns the hyperbolic cosine of s. + Returns the hyperbolic cosine of 's' in radians. + [codeblock] + # prints 1.543081 + print(cosh(1)) + [/codeblock] @@ -174,7 +254,11 @@ - Return the amount of decimals in the floating point value. + Returns the number of digit places after the decimal that the first non-zero digit occurs. + [codeblock] + # n is 2 + n = decimals(0.035) + [/codeblock] @@ -187,7 +271,11 @@ - Decreases time by a specified amount. + Returns the result of 'value' decreased by 'step' * 'amount'. + [codeblock] + # a = 59 + a = dectime(60, 10, 0.1)) + [/codeblock] @@ -196,7 +284,11 @@ - Convert from degrees to radians. + Returns degrees converted to radians. + [codeblock] + # r is 3.141593 + r = deg2rad(180) + [/codeblock] @@ -205,7 +297,7 @@ - Convert a previously converted instances to dictionary back into an instance. Useful for deserializing. + Convert a previously converted instance to dictionary back into an instance. Useful for deserializing. @@ -225,8 +317,12 @@ - Returns the base-e exponential function of s, which is e raised to the power s: e^s. + Returns [b]e[/b] raised to the power of 's'. [b]e[/b] sometimes called "Euler's number" is a mathematical constant whose value is approximately 2.71828. + [codeblock] + # a is 2.71828 + a = exp(2) + [/codeblock] @@ -234,8 +330,14 @@ - Rounds s downward, returning the largest integral value that is not greater than s. + Returns the largest integer value (rounded down) that is less than or equal to 's'. + [codeblock] + # a is 2 + a = floor(2.99) + # a is -3 + a = floor(-2.99) + [/codeblock] @@ -260,7 +362,26 @@ - Module (remainder of x/y) that wraps equally in positive and negative. + Returns the floating-point remainder of x/y that wraps equally in positive and negative. + [codeblock] + var i = -10; + while i < 0: + prints(i, fposmod(i, 10)) + i += 1 + [/codeblock] + Produces: + [codeblock] + -10 10 + -9 1 + -8 2 + -7 3 + -6 4 + -5 5 + -4 6 + -3 7 + -2 8 + -1 9 + [/codeblock] @@ -271,7 +392,15 @@ - Return a reference to the specified function. + Returns a reference to the specified function 'funcname' in object 'instance'. + [codeblock] + a = funcref(self, "foo") + a.call_func() + + func foo(): + print("bar") + [/codeblock] + Prints out "bar". This is a trivial example, the real power is that variable 'a' can be passed around to functions. @@ -280,7 +409,11 @@ - Hash the variable passed and return an integer. + Returns the integer hash of the variable passed. + [codeblock] + # print 177670 + print(hash("a")) + [/codeblock] @@ -289,7 +422,19 @@ - Convert a script class instance to a dictionary (useful for serializing). + Returns the passed instance converted a dictionary (useful for serializing). + [codeblock] + var foo = "bar" + func _ready(): + var d = inst2dict(self) + print(d.keys()) + print(d.values()) + [/codeblock] + Prints out: + [codeblock] + [@subpath, @path, foo] + [, res://test.gd, bar] + [/codeblock] @@ -298,7 +443,15 @@ - Get an object by its ID. + Returns the Object that corresponds to 'instance_id'. 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) + [/codeblock] + Prints "bar" @@ -323,7 +476,7 @@ - Returns whether s is an infinity value (either positive infinity or negative infinity). + Returns True/False whether 's' is an infinity value (either positive infinity or negative infinity). @@ -332,7 +485,7 @@ - Returns whether s is a NaN (Not-A-Number) value. + Returns True/False whether 's' is a NaN (Not-A-Number) value. @@ -341,7 +494,16 @@ - Returns the length of the given Variant if applicable. It will return character count of a String, element count of an Array, etc. +<<<<<<< HEAD + Returns length of Variant 'var'. Length is the character count of String, element count of Array, size of Dictionary, etc. Note: Generates a fatal error if Variant can not provide a length. +======= + Returns length of Variant 'var'. Length is the element count of an Array, size of a Dictionary, etc. Note: Generates a fatal error if Variant can not provide a length. +>>>>>>> 75b92e809dc95aefd3afab5a9efbd582a1a8d953 + [codeblock] + a = [1, 2, 3, 4] + print(len(a)) + [/codeblock] + Prints 4 @@ -372,7 +534,11 @@ - Load a resource from the filesystem, pass a valid path as argument. + Load a resource from the filesystem located at 'path'. Note: resource paths can be obtained by right clicking on a resource in the Assets Pannel and choosing "Copy Path". + [codeblock] + # load a scene called main located in the root of the project directory + var main = load("res://main.tscn") + [/codeblock] @@ -381,7 +547,11 @@ - Natural logarithm. + Natural logarithm. The amount of time needed to reach a certain level of continuous growth. Note: This is not the same as the log funcation on your calculator which is a base 10 logarithm. + [codeblock] + # a is 2.302585 + a = log(10) + [/codeblock] @@ -392,7 +562,13 @@ - Return the maximum of two values. + Returns the maximum of two values. + [codeblock] + # a is 2 + a = max(1,2) + # a is -3.99 + a = max(-3.99, -4) + [/codeblock] @@ -403,7 +579,13 @@ - Return the minimum of two values. + Returns the minimum of two values. + [codeblock] + # a is 1 + a = min(1,2) + # a is -4 + a = min(-3.99, -4) + [/codeblock] @@ -412,7 +594,15 @@ - Return the nearest larger power of 2 for an integer. + Returns the nearest larger power of 2 for an integer. + [codeblock] + # a is 4 + a = nearest_po2(3) + # a is 4 + a = nearest_po2(4) + # a is 8 + a = nearest_po2(5) + [/codeblock] @@ -423,6 +613,13 @@ 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 every numerical values to [float] types. + [codeblock] + p = parse_json('["a", "b", "c"]') + if typeof(p) == TYPE_ARRAY: + print(p[0]) + else: + print("unexpected results") + [/codeblock] @@ -433,7 +630,11 @@ - Power function, x elevate to y. + Returns the result of 'x' raised to the power of 'y'. + [codeblock] + # a is 32 + a = pow(2,5) + [/codeblock] @@ -442,14 +643,22 @@ - Preload a resource from the filesystem. The resource is loaded during script parsing. + Returns a resource from the filesystem that is loaded during script parsing. Note: resource paths can be obtained by right clicking on a resource in the Assets Pannel and choosing "Copy Path". + [codeblock] + # load a scene called main located in the root of the project directory + var main = preload("res://main.tscn") - Print one or more arguments to strings in the best way possible to a console line. + 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) + [/codeblock] + Prints ab[1, 2, 3] diff --git a/modules/gdscript/gd_functions.cpp b/modules/gdscript/gd_functions.cpp index 04752dc71a..34d01c6beb 100644 --- a/modules/gdscript/gd_functions.cpp +++ b/modules/gdscript/gd_functions.cpp @@ -1420,12 +1420,12 @@ MethodInfo GDFunctions::get_info(Function p_func) { } break; case MATH_ISNAN: { MethodInfo mi("is_nan", PropertyInfo(Variant::REAL, "s")); - mi.return_val.type = Variant::REAL; + mi.return_val.type = Variant::BOOL; return mi; } break; case MATH_ISINF: { MethodInfo mi("is_inf", PropertyInfo(Variant::REAL, "s")); - mi.return_val.type = Variant::REAL; + mi.return_val.type = Variant::BOOL; return mi; } break; case MATH_EASE: { -- cgit v1.2.3