From c6dcf3310d1fbf635232208d8c666078be5e481a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Tue, 17 Nov 2020 11:21:08 +0100 Subject: [PATCH] doc: Sync classref with Variant utility methods Copied relevant documentation from the original `@GDScript` built-ins, which will likely be removed in a future commit. Various fixups to `variant_utility.cpp` while working on this. --- core/variant/variant_utility.cpp | 81 +-- doc/classes/@GlobalScope.xml | 1141 ++++++++++++++++++++++++++++++ doc/classes/JSONParser.xml | 57 ++ doc/classes/Popup.xml | 2 + 4 files changed, 1235 insertions(+), 46 deletions(-) create mode 100644 doc/classes/JSONParser.xml diff --git a/core/variant/variant_utility.cpp b/core/variant/variant_utility.cpp index 91a1b0262c..70edcd48c2 100644 --- a/core/variant/variant_utility.cpp +++ b/core/variant/variant_utility.cpp @@ -40,12 +40,15 @@ struct VariantUtilityFunctions { // Math + static inline double sin(double arg) { return Math::sin(arg); } + static inline double cos(double arg) { return Math::cos(arg); } + static inline double tan(double arg) { return Math::tan(arg); } @@ -53,9 +56,11 @@ struct VariantUtilityFunctions { static inline double sinh(double arg) { return Math::sinh(arg); } + static inline double cosh(double arg) { return Math::cosh(arg); } + static inline double tanh(double arg) { return Math::tanh(arg); } @@ -63,9 +68,11 @@ struct VariantUtilityFunctions { static inline double asin(double arg) { return Math::asin(arg); } + static inline double acos(double arg) { return Math::acos(arg); } + static inline double atan(double arg) { return Math::atan(arg); } @@ -173,6 +180,7 @@ struct VariantUtilityFunctions { static inline double pow(double x, double y) { return Math::pow(x, y); } + static inline double log(double x) { return Math::log(x); } @@ -181,24 +189,24 @@ struct VariantUtilityFunctions { return Math::exp(x); } - static inline double is_nan(double x) { + static inline bool is_nan(double x) { return Math::is_nan(x); } - static inline double is_inf(double x) { + static inline bool is_inf(double x) { return Math::is_inf(x); } - static inline double is_equal_approx(double x, double y) { + static inline bool is_equal_approx(double x, double y) { return Math::is_equal_approx(x, y); } - static inline double is_zero_approx(double x) { + static inline bool is_zero_approx(double x) { return Math::is_zero_approx(x); } - static inline double ease(float x, float c) { - return Math::ease(x, c); + static inline double ease(float x, float curve) { + return Math::ease(x, curve); } static inline int step_decimals(float step) { @@ -268,6 +276,7 @@ struct VariantUtilityFunctions { static inline int64_t wrapi(int64_t value, int64_t min, int64_t max) { return Math::wrapi(value, min, max); } + static inline double wrapf(double value, double min, double max) { return Math::wrapf(value, min, max); } @@ -695,9 +704,9 @@ struct VariantUtilityFunctions { return p_arr.hash(); } - static inline Variant instance_from_id(int64_t p_id) { + static inline Object *instance_from_id(int64_t p_id) { ObjectID id = ObjectID((uint64_t)p_id); - Variant ret = ObjectDB::get_instance(id); + Object *ret = ObjectDB::get_instance(id); return ret; } @@ -829,22 +838,18 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { static void call(Variant *r_ret, const Variant **p_args, int p_argcount, Callable::CallError &r_error) { \ call_helperr(VariantUtilityFunctions::m_func, r_ret, p_args, r_error); \ } \ - \ static void validated_call(Variant *r_ret, const Variant **p_args, int p_argcount) { \ validated_call_helperr(VariantUtilityFunctions::m_func, r_ret, p_args); \ } \ static void ptrcall(void *ret, const void **p_args, int p_argcount) { \ ptr_call_helperr(VariantUtilityFunctions::m_func, ret, p_args); \ } \ - \ static int get_argument_count() { \ return get_arg_count_helperr(VariantUtilityFunctions::m_func); \ } \ - \ static Variant::Type get_argument_type(int p_arg) { \ return get_arg_type_helperr(VariantUtilityFunctions::m_func, p_arg); \ } \ - \ static Variant::Type get_return_type() { \ return get_ret_type_helperr(VariantUtilityFunctions::m_func); \ } \ @@ -863,7 +868,6 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { r_error.error = Callable::CallError::CALL_OK; \ *r_ret = VariantUtilityFunctions::m_func(*p_args[0], r_error); \ } \ - \ static void validated_call(Variant *r_ret, const Variant **p_args, int p_argcount) { \ Callable::CallError ce; \ *r_ret = VariantUtilityFunctions::m_func(*p_args[0], ce); \ @@ -872,15 +876,12 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { Callable::CallError ce; \ PtrToArg::encode(VariantUtilityFunctions::m_func(PtrToArg::convert(p_args[0]), ce), ret); \ } \ - \ static int get_argument_count() { \ return 1; \ } \ - \ static Variant::Type get_argument_type(int p_arg) { \ return Variant::NIL; \ } \ - \ static Variant::Type get_return_type() { \ return Variant::NIL; \ } \ @@ -899,7 +900,6 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { r_error.error = Callable::CallError::CALL_OK; \ *r_ret = VariantUtilityFunctions::m_func(*p_args[0], *p_args[1], *p_args[2], r_error); \ } \ - \ static void validated_call(Variant *r_ret, const Variant **p_args, int p_argcount) { \ Callable::CallError ce; \ *r_ret = VariantUtilityFunctions::m_func(*p_args[0], *p_args[1], *p_args[2], ce); \ @@ -910,15 +910,12 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { r = VariantUtilityFunctions::m_func(PtrToArg::convert(p_args[0]), PtrToArg::convert(p_args[1]), PtrToArg::convert(p_args[2]), ce); \ PtrToArg::encode(r, ret); \ } \ - \ static int get_argument_count() { \ return 3; \ } \ - \ static Variant::Type get_argument_type(int p_arg) { \ return Variant::NIL; \ } \ - \ static Variant::Type get_return_type() { \ return Variant::NIL; \ } \ @@ -937,7 +934,6 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { r_error.error = Callable::CallError::CALL_OK; \ *r_ret = VariantUtilityFunctions::m_func(p_args, p_argcount, r_error); \ } \ - \ static void validated_call(Variant *r_ret, const Variant **p_args, int p_argcount) { \ Callable::CallError c; \ *r_ret = VariantUtilityFunctions::m_func(p_args, p_argcount, c); \ @@ -955,15 +951,12 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { validated_call(&r, (const Variant **)argsp.ptr(), p_argcount); \ PtrToArg::encode(r, ret); \ } \ - \ static int get_argument_count() { \ return 2; \ } \ - \ static Variant::Type get_argument_type(int p_arg) { \ return Variant::NIL; \ } \ - \ static Variant::Type get_return_type() { \ return Variant::NIL; \ } \ @@ -986,7 +979,6 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { r_error.error = Callable::CallError::CALL_OK; \ *r_ret = VariantUtilityFunctions::m_func(p_args, p_argcount, r_error); \ } \ - \ static void validated_call(Variant *r_ret, const Variant **p_args, int p_argcount) { \ Callable::CallError c; \ *r_ret = VariantUtilityFunctions::m_func(p_args, p_argcount, c); \ @@ -1004,15 +996,12 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { validated_call(&r, (const Variant **)argsp.ptr(), p_argcount); \ PtrToArg::encode(r.operator String(), ret); \ } \ - \ static int get_argument_count() { \ return 1; \ } \ - \ static Variant::Type get_argument_type(int p_arg) { \ return Variant::NIL; \ } \ - \ static Variant::Type get_return_type() { \ return Variant::STRING; \ } \ @@ -1035,7 +1024,6 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { r_error.error = Callable::CallError::CALL_OK; \ VariantUtilityFunctions::m_func(p_args, p_argcount, r_error); \ } \ - \ static void validated_call(Variant *r_ret, const Variant **p_args, int p_argcount) { \ Callable::CallError c; \ VariantUtilityFunctions::m_func(p_args, p_argcount, c); \ @@ -1052,15 +1040,12 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { Variant r; \ validated_call(&r, (const Variant **)argsp.ptr(), p_argcount); \ } \ - \ static int get_argument_count() { \ return 1; \ } \ - \ static Variant::Type get_argument_type(int p_arg) { \ return Variant::NIL; \ } \ - \ static Variant::Type get_return_type() { \ return Variant::NIL; \ } \ @@ -1082,22 +1067,18 @@ static _FORCE_INLINE_ Variant::Type get_ret_type_helper(void (*p_func)(P...)) { static void call(Variant *r_ret, const Variant **p_args, int p_argcount, Callable::CallError &r_error) { \ call_helper(VariantUtilityFunctions::m_func, p_args, r_error); \ } \ - \ static void validated_call(Variant *r_ret, const Variant **p_args, int p_argcount) { \ validated_call_helper(VariantUtilityFunctions::m_func, p_args); \ } \ static void ptrcall(void *ret, const void **p_args, int p_argcount) { \ ptr_call_helper(VariantUtilityFunctions::m_func, p_args); \ } \ - \ static int get_argument_count() { \ return get_arg_count_helper(VariantUtilityFunctions::m_func); \ } \ - \ static Variant::Type get_argument_type(int p_arg) { \ return get_arg_type_helper(VariantUtilityFunctions::m_func, p_arg); \ } \ - \ static Variant::Type get_return_type() { \ return get_ret_type_helper(VariantUtilityFunctions::m_func); \ } \ @@ -1187,7 +1168,7 @@ void Variant::_register_variant_utility_functions() { FUNCBINDR(signf, sarray("x"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(signi, sarray("x"), Variant::UTILITY_FUNC_TYPE_MATH); - FUNCBINDR(pow, sarray("x", "y"), Variant::UTILITY_FUNC_TYPE_MATH); + FUNCBINDR(pow, sarray("base", "exp"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(log, sarray("x"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(exp, sarray("x"), Variant::UTILITY_FUNC_TYPE_MATH); @@ -1197,17 +1178,17 @@ void Variant::_register_variant_utility_functions() { FUNCBINDR(is_equal_approx, sarray("a", "b"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(is_zero_approx, sarray("x"), Variant::UTILITY_FUNC_TYPE_MATH); - FUNCBINDR(ease, sarray("x", "c"), Variant::UTILITY_FUNC_TYPE_MATH); + FUNCBINDR(ease, sarray("x", "curve"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(step_decimals, sarray("x"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(range_step_decimals, sarray("x"), Variant::UTILITY_FUNC_TYPE_MATH); - FUNCBINDR(stepify, sarray("x", "y"), Variant::UTILITY_FUNC_TYPE_MATH); + FUNCBINDR(stepify, sarray("x", "step"), Variant::UTILITY_FUNC_TYPE_MATH); - FUNCBINDR(lerp, sarray("from", "to", "c"), Variant::UTILITY_FUNC_TYPE_MATH); - FUNCBINDR(lerp_angle, sarray("from", "to", "c"), Variant::UTILITY_FUNC_TYPE_MATH); - FUNCBINDR(inverse_lerp, sarray("from", "to", "c"), Variant::UTILITY_FUNC_TYPE_MATH); + FUNCBINDR(lerp, sarray("from", "to", "weight"), Variant::UTILITY_FUNC_TYPE_MATH); + FUNCBINDR(lerp_angle, sarray("from", "to", "weight"), Variant::UTILITY_FUNC_TYPE_MATH); + FUNCBINDR(inverse_lerp, sarray("from", "to", "weight"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(range_lerp, sarray("value", "istart", "istop", "ostart", "ostop"), Variant::UTILITY_FUNC_TYPE_MATH); - FUNCBINDR(smoothstep, sarray("from", "to", "c"), Variant::UTILITY_FUNC_TYPE_MATH); + FUNCBINDR(smoothstep, sarray("from", "to", "x"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(move_toward, sarray("from", "to", "delta"), Variant::UTILITY_FUNC_TYPE_MATH); FUNCBINDR(dectime, sarray("value", "amount", "step"), Variant::UTILITY_FUNC_TYPE_MATH); @@ -1238,7 +1219,7 @@ void Variant::_register_variant_utility_functions() { FUNCBINDR(nearest_po2, sarray("value"), Variant::UTILITY_FUNC_TYPE_MATH); - //Random + // Random FUNCBIND(randomize, sarray(), Variant::UTILITY_FUNC_TYPE_RANDOM); FUNCBINDR(randi, sarray(), Variant::UTILITY_FUNC_TYPE_RANDOM); @@ -1249,7 +1230,8 @@ void Variant::_register_variant_utility_functions() { FUNCBINDR(rand_from_seed, sarray("seed"), Variant::UTILITY_FUNC_TYPE_RANDOM); // Utility - FUNCBINDVR(weakref, sarray("from"), Variant::UTILITY_FUNC_TYPE_GENERAL); + + FUNCBINDVR(weakref, sarray("obj"), Variant::UTILITY_FUNC_TYPE_GENERAL); FUNCBINDR(_typeof, sarray("variable"), Variant::UTILITY_FUNC_TYPE_GENERAL); FUNCBINDVARARGS(str, sarray(), Variant::UTILITY_FUNC_TYPE_GENERAL); FUNCBINDVARARGV(print, sarray(), Variant::UTILITY_FUNC_TYPE_GENERAL); @@ -1271,10 +1253,11 @@ void Variant::_register_variant_utility_functions() { FUNCBINDR(hash, sarray("variable"), Variant::UTILITY_FUNC_TYPE_GENERAL); - FUNCBINDR(instance_from_id, sarray("id"), Variant::UTILITY_FUNC_TYPE_GENERAL); + FUNCBINDR(instance_from_id, sarray("instance_id"), Variant::UTILITY_FUNC_TYPE_GENERAL); FUNCBINDR(is_instance_id_valid, sarray("id"), Variant::UTILITY_FUNC_TYPE_GENERAL); FUNCBINDR(is_instance_valid, sarray("instance"), Variant::UTILITY_FUNC_TYPE_GENERAL); } + void Variant::_unregister_variant_utility_functions() { utility_function_table.clear(); utility_function_name_table.clear(); @@ -1318,6 +1301,7 @@ Variant::ValidatedUtilityFunction Variant::get_validated_utility_function(const return bfi->validated_call_utility; } + Variant::PTRUtilityFunction Variant::get_ptr_utility_function(const StringName &p_name) { const VariantUtilityFunctionInfo *bfi = utility_function_table.lookup_ptr(p_name); if (!bfi) { @@ -1344,6 +1328,7 @@ int Variant::get_utility_function_argument_count(const StringName &p_name) { return bfi->argcount; } + Variant::Type Variant::get_utility_function_argument_type(const StringName &p_name, int p_arg) { const VariantUtilityFunctionInfo *bfi = utility_function_table.lookup_ptr(p_name); if (!bfi) { @@ -1352,6 +1337,7 @@ Variant::Type Variant::get_utility_function_argument_type(const StringName &p_na return bfi->get_arg_type(p_arg); } + String Variant::get_utility_function_argument_name(const StringName &p_name, int p_arg) { const VariantUtilityFunctionInfo *bfi = utility_function_table.lookup_ptr(p_name); if (!bfi) { @@ -1361,6 +1347,7 @@ String Variant::get_utility_function_argument_name(const StringName &p_name, int ERR_FAIL_INDEX_V(p_arg, bfi->argnames.size(), String()); return bfi->argnames[p_arg]; } + bool Variant::has_utility_function_return_value(const StringName &p_name) { const VariantUtilityFunctionInfo *bfi = utility_function_table.lookup_ptr(p_name); if (!bfi) { @@ -1368,6 +1355,7 @@ bool Variant::has_utility_function_return_value(const StringName &p_name) { } return bfi->returns_value; } + Variant::Type Variant::get_utility_function_return_type(const StringName &p_name) { const VariantUtilityFunctionInfo *bfi = utility_function_table.lookup_ptr(p_name); if (!bfi) { @@ -1376,6 +1364,7 @@ Variant::Type Variant::get_utility_function_return_type(const StringName &p_name return bfi->return_type; } + bool Variant::is_utility_function_vararg(const StringName &p_name) { const VariantUtilityFunctionInfo *bfi = utility_function_table.lookup_ptr(p_name); if (!bfi) { diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index ee65bbc07e..f6b1bb4d7c 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -10,6 +10,1147 @@ + + + + + + + + + + + + + + + Returns the absolute value of float parameter [code]x[/code] (i.e. positive value). + [codeblock] + # a is 1.2 + a = absf(-1.2) + [/codeblock] + + + + + + + + + Returns the absolute value of int parameter [code]x[/code] (i.e. positive value). + [codeblock] + # a is 1 + a = absi(-1) + [/codeblock] + + + + + + + + + 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] + + + + + + + + + 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] + + + + + + + + + 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] + + + + + + + + + + + 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] + + + + + + + + + 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]. + + + + + + + + + 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). + + + + + + + + + + + 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). + + + + + + + + + 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]. + + + + + + + + + + + + + + + + + + + + + + + + + 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] + + + + + + + + + + + + + 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] + + + + + + + + + Returns the cosine of angle [code]angle_rad[/code] in radians. + [codeblock] + # Prints 1 then -1 + print(cos(PI * 2)) + print(cos(PI)) + [/codeblock] + + + + + + + + + Returns the hyperbolic cosine of [code]x[/code] in radians. + [codeblock] + # Prints 1.543081 + print(cosh(1)) + [/codeblock] + + + + + + + + + Converts from decibels to linear energy (audio). + + + + + + + + + + + + + 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] + + + + + + + + + Converts an angle expressed in degrees to radians. + [codeblock] + # r is 3.141593 + r = deg2rad(180) + [/codeblock] + + + + + + + + + + + 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. + + + + + + + + + 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] + + + + + + + + + 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. + + + + + + + + + + + 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. + + + + + + + + + + + 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] + + + + + + + + + Returns the integer hash of the variable passed. + [codeblock] + print(hash("a")) # Prints 177670 + [/codeblock] + + + + + + + + + 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] + + + + + + + + + + + + + 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] + + + + + + + + + + + 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. + + + + + + + + + Returns whether [code]x[/code] is an infinity value (either positive infinity or negative infinity). + + + + + + + + + + + + + + + + + Returns whether [code]instance[/code] is a valid object (e.g. has not been deleted from memory). + + + + + + + + + Returns whether [code]x[/code] is a NaN ("Not a Number" or invalid) value. + + + + + + + + + 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. + + + + + + + + + + + + + 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] + + + + + + + + + + + + + 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] + + + + + + + + + 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] + + + + + + + + + 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]. + + + + + + + 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] + + + + + + + + + + + Returns the maximum of two float values. + [codeblock] + maxf(3.6, 24) # Returns 24.0 + maxf(-3.99, -4) # Returns -3.99 + [/codeblock] + + + + + + + + + + + Returns the maximum of two int values. + [codeblock] + maxi(1, 2) # Returns 2 + maxi(-3, -4) # Returns -3 + [/codeblock] + + + + + + + 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] + + + + + + + + + + + Returns the minimum of two float values. + [codeblock] + minf(3.6, 24) # Returns 3.6 + minf(-3.99, -4) # Returns -4.0 + [/codeblock] + + + + + + + + + + + Returns the minimum of two int values. + [codeblock] + mini(1, 2) # Returns 1 + mini(-3, -4) # Returns -4 + [/codeblock] + + + + + + + + + + + + + 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] + + + + + + + + + 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). + + + + + + + + + + + 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). + + + + + + + + + + + Returns the result of [code]base[/code] raised to the power of [code]exp[/code]. + [codeblock] + pow(2, 5) # Returns 32 + [/codeblock] + + + + + 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. + + + + + Prints one or more arguments to strings in the best way possible to standard error line. + [codeblock] + printerr("prints to stderr") + [/codeblock] + + + + + 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]. + + + + + Prints one or more arguments to the console with a space between each argument. + [codeblock] + prints("A", "B", "C") # Prints A B C + [/codeblock] + + + + + Prints one or more arguments to the console with a tab between each argument. + [codeblock] + printt("A", "B", "C") # Prints A B C + [/codeblock] + + + + + 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. + + + + + 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] + + + + + + + + + Converts an angle expressed in radians to degrees. + [codeblock] + rad2deg(0.523599) # Returns 30 + [/codeblock] + + + + + + + + + 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. + + + + + + + Returns a random floating point value on the interval [code][0, 1][/code]. + [codeblock] + randf() # Returns e.g. 0.375671 + [/codeblock] + + + + + + + + + + + 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] + + + + + + + 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] + + + + + + + + + + + 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] + + + + + 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] + + + + + + + + + + + + + + + + + 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] + + + + + + + + + + + + + + + + + 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]. + + + + + + + Sets seed for the random number generator. + [codeblock] + my_seed = "Godot Rocks" + seed(my_seed.hash()) + [/codeblock] + + + + + + + + + + + + + + + + + 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] + + + + + + + + + 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] + + + + + + + + + Returns the sine of angle [code]angle_rad[/code] in radians. + [codeblock] + sin(0.523599) # Returns 0.5 + [/codeblock] + + + + + + + + + Returns the hyperbolic sine of [code]x[/code]. + [codeblock] + a = log(2.0) # Returns 0.693147 + sinh(a) # Returns 0.75 + [/codeblock] + + + + + + + + + + + + + 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] + + + + + + + + + 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#. + + + + + + + + + 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] + + + + + + + + + + + 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]. + + + + + + + Converts one or more arguments to string in the best way possible. + + + + + + + + + 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] + + + + + + + + + Returns the tangent of angle [code]angle_rad[/code] in radians. + [codeblock] + tan(deg2rad(45)) # Returns 1 + [/codeblock] + + + + + + + + + Returns the hyperbolic tangent of [code]x[/code]. + [codeblock] + a = log(2.0) # Returns 0.693147 + tanh(a) # Returns 0.6 + [/codeblock] + + + + + + + + + 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] + + + + + + + + + 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]. + + + + + + + + + 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]. + + + + + + + + + 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] + + + + + + + + + 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. + + + + + + + + + + + + + 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. + + + + + + + + + + + + + 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] + + 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 @@ + +