From 7e4dffcaee5236b55967c28ea2dc4260278d7857 Mon Sep 17 00:00:00 2001 From: Julian Murgia Date: Tue, 27 Jun 2017 13:53:11 +0200 Subject: [PATCH] Added a better description for types operations (floats, integers), fixes #377 (cherry picked from commit af28c7515e1dda9e516928bf4bd02787ac07fe38) --- .../scripting/gdscript/gdscript_basics.rst | 165 +++++++++--------- 1 file changed, 87 insertions(+), 78 deletions(-) diff --git a/learning/scripting/gdscript/gdscript_basics.rst b/learning/scripting/gdscript/gdscript_basics.rst index f420eb2cf..fc4b3b029 100644 --- a/learning/scripting/gdscript/gdscript_basics.rst +++ b/learning/scripting/gdscript/gdscript_basics.rst @@ -7,9 +7,9 @@ Introduction ------------ *GDScript* is a high level, dynamically typed programming language used to -create content. It uses a syntax similar to -`Python `_ -(blocks are indent-based and many keywords are similar). Its goal is +create content. It uses a syntax similar to +`Python `_ +(blocks are indent-based and many keywords are similar). Its goal is to be optimized for and tightly integrated with Godot Engine, allowing great flexibility for content creation and integration. @@ -28,7 +28,7 @@ enormous amount of code. After some experiments with The last third party scripting language that was used for shipped games was `Squirrel `__, but it was dropped as well. -At that point, it became evident that a custom scripting language could +At that point, it became evident that a custom scripting language could more optimally make use of Godot's particular architecture: - Godot embeds scripts in nodes. Most languages are not designed with @@ -65,7 +65,7 @@ here's a simple example of how GDScript looks. # member variables - var a = 5 + var a = 5 var s = "Hello" var arr = [1, 2, 3] var dict = {"key":"value", 2:3} @@ -126,9 +126,9 @@ read this tutorial: :ref:`doc_gdscript_more_efficiently`. Language -------- -In the following, an overview is given to GDScript. Details, such as which +In the following, an overview is given to GDScript. Details, such as which methods are available to arrays or other objects, should be looked up in -the linked class descriptions. +the linked class descriptions. Identifiers ~~~~~~~~~~~ @@ -218,6 +218,15 @@ The following is the list of supported operators and their precedence | ``-x`` | Negative | +---------------------------------------------------------------+-----------------------------------------+ | ``*`` ``/`` ``%`` | Multiplication / Division / Remainder | +| | | +| | NOTE: The result of these operations | +| | depends on the operands types. If both | +| | are Integers, then the result will be | +| | an Integer. That means 1/10 returns 0 | +| | instead of 0.1. If at least one of the | +| | operands is a float, then the result is | +| | a float: float(1)/10 or 1.0/10 return | +| | both 0.1. | +---------------------------------------------------------------+-----------------------------------------+ | ``+`` ``-`` | Addition / Subtraction | +---------------------------------------------------------------+-----------------------------------------+ @@ -274,13 +283,13 @@ considered a comment. # This is a comment .. Uncomment me if/when https://github.com/godotengine/godot/issues/1320 gets fixed - + Multi-line comments can be created using """ (three quotes in a row) at the beginning and end of a block of text. - + :: - - """ Everything on these + + """ Everything on these lines is considered a comment """ @@ -296,7 +305,7 @@ null ^^^^ ``null`` is an empty data type that contains no information and can not -be assigned any other value. +be assigned any other value. bool ^^^^ @@ -426,7 +435,7 @@ Container built-in types :ref:`Array ` ^^^^^^^^^^^^^^^^^^^^^^^^^^ -Generic sequence of arbitrary object types, including other arrays or dictionaries (see below). +Generic sequence of arbitrary object types, including other arrays or dictionaries (see below). The array can resize dynamically. Arrays are indexed starting from index ``0``. Starting with Godot 2.1, indices may be negative like in Python, to count from the end. @@ -442,10 +451,10 @@ Starting with Godot 2.1, indices may be negative like in Python, to count from t GDScript arrays are allocated linearly in memory for speed. Very large arrays (more than tens of thousands of elements) may however cause -memory fragmentation. If this is a concern special types of -arrays are available. These only accept a single data type. They avoid memory +memory fragmentation. If this is a concern special types of +arrays are available. These only accept a single data type. They avoid memory fragmentation and also use less memory but are atomic and tend to run slower than generic -arrays. They are therefore only recommended to use for very large data sets: +arrays. They are therefore only recommended to use for very large data sets: - :ref:`ByteArray `: An array of bytes (integers from 0 to 255). - :ref:`IntArray `: An array of integers. @@ -471,15 +480,15 @@ Associative container which contains values referenced by unique keys. "morekey" : "Hello" } -Lua-style table syntax is also supported. Lua-style uses ``=`` instead of ``:`` -and doesn't use quotes to mark string keys (making for slightly less to write). -Note however that like any GDScript identifier, keys written in this form cannot +Lua-style table syntax is also supported. Lua-style uses ``=`` instead of ``:`` +and doesn't use quotes to mark string keys (making for slightly less to write). +Note however that like any GDScript identifier, keys written in this form cannot start with a digit. :: var d = { - test22 = "Value", + test22 = "Value", somekey = 2, otherkey = [2,3,4], morekey = "Hello" @@ -514,7 +523,7 @@ Constants ~~~~~~~~~ Constants are similar to variables, but must be constants or constant -expressions and must be assigned on initialization. +expressions and must be assigned on initialization. :: @@ -525,7 +534,7 @@ expressions and must be assigned on initialization. const e = [1, 2, 3, 4][0] # constant expression: 1 const f = sin(20) # sin() can be used in constant expressions const g = x + 20 # invalid; this is not a constant expression! - + Enums ^^^^^ @@ -589,13 +598,13 @@ function or be returned from other functions. This is for performance reasons. To reference a function by name at runtime, (e.g. to store it in a variable, or pass it to another function as an argument) one must use the ``call`` or ``funcref`` helpers:: - - # Call a function by name in one step - mynode.call("myfunction", args) - # Store a function reference + # Call a function by name in one step + mynode.call("myfunction", args) + + # Store a function reference var myfunc = funcref(mynode, "myfunction") - # Call stored function reference + # Call stored function reference myfunc.call_func(args) @@ -603,7 +612,7 @@ Remember that default functions like ``_init``, and most notifications such as ``_enter_tree``, ``_exit_tree``, ``_process``, ``_fixed_process``, etc. are called in all base classes automatically. So there is only a need to call the function explicitly when overloading -them in some way. +them in some way. Static functions @@ -709,7 +718,7 @@ separate threads without the user knowing). In the same way, member variables (including arrays and dictionaries) are initialized every time an instance is created. -Below is an example of a class file. +Below is an example of a class file. :: @@ -723,29 +732,29 @@ Below is an example of a class file. Inheritance ^^^^^^^^^^^ -A class (stored as a file) can inherit from +A class (stored as a file) can inherit from - A global class -- Another class file -- An inner class inside another class file. +- Another class file +- An inner class inside another class file. -Multiple inheritance is not allowed. +Multiple inheritance is not allowed. Inheritance uses the ``extends`` keyword: :: # Inherit/extend a globally available class - extends SomeClass - + extends SomeClass + # Inherit/extend a named class file - extends "somefile.gd" - + extends "somefile.gd" + # Inherit/extend an inner class in another file extends "somefile.gd".SomeInnerClass -To check if a given instance inherits from a given class +To check if a given instance inherits from a given class the ``extends`` keyword can be used as an operator instead: :: @@ -762,7 +771,7 @@ the ``extends`` keyword can be used as an operator instead: Class Constructor ^^^^^^^^^^^^^^^^^ -The class constructor, called on class instantiation, is named ``_init``. +The class constructor, called on class instantiation, is named ``_init``. As mentioned earlier, the constructors of parent classes are called automatically when inheriting a class. So there is usually no need to call ``._init()`` explicitly. @@ -777,7 +786,7 @@ Inner classes ^^^^^^^^^^^^^ A class file can contain inner classes. Inner classes are defined using the -``class`` keyword. They are instanced using the ``ClassName.new()`` +``class`` keyword. They are instanced using the ``ClassName.new()`` function. :: @@ -792,7 +801,7 @@ function. # This is the constructor of the class file's main class func _init(): - var c = SomeInnerClass.new() + var c = SomeInnerClass.new() c.print_value_of_a() Classes as resources @@ -835,12 +844,12 @@ special export syntax is provided. :: - # If the exported value assigns a constant or constant expression, + # If the exported value assigns a constant or constant expression, # the type will be inferred and used in the editor export var number = 5 - # Export can take a basic data type as an argument which will be + # Export can take a basic data type as an argument which will be # used in the editor export(int) var number @@ -853,49 +862,49 @@ special export syntax is provided. # Integers and strings hint enumerated values # Editor will enumerate as 0, 1 and 2 - export(int, "Warrior", "Magician", "Thief") var character_class - # Editor will enumerate with string names - export(String, "Rebecca", "Mary", "Leah") var character_name + export(int, "Warrior", "Magician", "Thief") var character_class + # Editor will enumerate with string names + export(String, "Rebecca", "Mary", "Leah") var character_name # Strings as paths # String is a path to a file - export(String, FILE) var f + export(String, FILE) var f # String is a path to a directory - export(String, DIR) var f + export(String, DIR) var f # String is a path to a file, custom filter provided as hint - export(String, FILE, "*.txt") var f + export(String, FILE, "*.txt") var f - # Using paths in the global filesystem is also possible, + # Using paths in the global filesystem is also possible, # but only in tool scripts (see further below) # String is a path to a PNG file in the global filesystem - export(String, FILE, GLOBAL, "*.png") var tool_image + export(String, FILE, GLOBAL, "*.png") var tool_image # String is a path to a directory in the global filesystem export(String, DIR, GLOBAL) var tool_dir - # The MULTILINE setting tells the editor to show a large input + # The MULTILINE setting tells the editor to show a large input # field for editing over multiple lines export(String, MULTILINE) var text # Limiting editor input ranges # Allow integer values from 0 to 20 - export(int, 20) var i - # Allow integer values from -10 to 20 - export(int, -10, 20) var j + export(int, 20) var i + # Allow integer values from -10 to 20 + export(int, -10, 20) var j # Allow floats from -10 to 20, with a step of 0.2 - export(float, -10, 20, 0.2) var k - # Allow values y = exp(x) where y varies betwee 100 and 1000 - # while snapping to steps of 20. The editor will present a - # slider for easily editing the value. - export(float, EXP, 100, 1000, 20) var l + export(float, -10, 20, 0.2) var k + # Allow values y = exp(x) where y varies betwee 100 and 1000 + # while snapping to steps of 20. The editor will present a + # slider for easily editing the value. + export(float, EXP, 100, 1000, 20) var l # Floats with easing hint - # Display a visual representation of the ease() function + # Display a visual representation of the ease() function # when editing - export(float, EASE) var transition_speed + export(float, EASE) var transition_speed # Colors @@ -903,9 +912,9 @@ special export syntax is provided. export(Color, RGB) var col # Color is RGB # Color given as Red-Green-Blue-Alpha value export(Color, RGBA) var col # Color is RGBA - + # another node in the scene can be exported too - + export(NodePath) var node It must be noted that even if the script is not being run while at the @@ -922,7 +931,7 @@ can be set from the editor: :: # Individually edit the bits of an integer - export(int, FLAGS) var spell_elements = ELEMENT_WIND | ELEMENT_WATER + export(int, FLAGS) var spell_elements = ELEMENT_WIND | ELEMENT_WATER Restricting the flags to a certain number of named flags is also possible. The syntax is very similar to the enumeration syntax: @@ -930,7 +939,7 @@ possible. The syntax is very similar to the enumeration syntax: :: # Set any of the given flags from the editor - export(int, FLAGS, "Fire", "Water", "Earth", "Wind") var spell_elements = 0 + export(int, FLAGS, "Fire", "Water", "Earth", "Wind") var spell_elements = 0 In this example, ``Fire`` has value 1, ``Water`` has value 2, ``Earth`` has value 4 and ``Wind`` corresponds to value 8. Usually, constants @@ -971,21 +980,21 @@ initializers, but they must be constant expressions. Setters/getters ~~~~~~~~~~~~~~~ -It is often useful to know when a class' member variable changes for -whatever reason. It may also be desired to encapsulate its access in some way. +It is often useful to know when a class' member variable changes for +whatever reason. It may also be desired to encapsulate its access in some way. -For this, GDScript provides a *setter/getter* syntax using the ``setget`` keyword. +For this, GDScript provides a *setter/getter* syntax using the ``setget`` keyword. It is used directly after a variable definition: :: var variable = value setget setterfunc, getterfunc -Whenever the value of ``variable`` is modified by an *external* source +Whenever the value of ``variable`` is modified by an *external* source (i.e. not from local usage in the class), the *setter* function (``setterfunc`` above) -will be called. This happens *before* the value is changed. The *setter* must decide what to do -with the new value. Vice-versa, when ``variable`` is accessed, the *getter* function -(``getterfunc`` above) must ``return`` the desired value. Below is an example: +will be called. This happens *before* the value is changed. The *setter* must decide what to do +with the new value. Vice-versa, when ``variable`` is accessed, the *getter* function +(``getterfunc`` above) must ``return`` the desired value. Below is an example: :: @@ -1010,8 +1019,8 @@ Either of the *setter* or *getter* functions can be omitted: Get/Setters are especially useful when exporting variables to editor in tool scripts or plugins, for validating input. -As said *local* access will *not* trigger the setter and getter. Here is an -illustration of this: +As said *local* access will *not* trigger the setter and getter. Here is an +illustration of this: :: @@ -1019,7 +1028,7 @@ illustration of this: # Does not trigger setter/getter myinteger=5 print(myinteger) - + # Does trigger setter/getter self.myinteger=5 print(self.myinteger) @@ -1058,7 +1067,7 @@ Signals It is often desired to send a notification that something happened in an instance. GDScript supports creation of built-in Godot signals. -Declaring a signal in GDScript is easy using the `signal` keyword. +Declaring a signal in GDScript is easy using the `signal` keyword. :: @@ -1116,7 +1125,7 @@ Object.emit_signal method: Coroutines ~~~~~~~~~~ -GDScript offers support for `coroutines `_ +GDScript offers support for `coroutines `_ via the ``yield`` built-in function. Calling ``yield()`` will immediately return from the current function, with the current frozen state of the same function as the return value. Calling ``resume`` on