diff options
Diffstat (limited to 'doc/gdscript.lyx')
| -rw-r--r-- | doc/gdscript.lyx | 2531 |
1 files changed, 2531 insertions, 0 deletions
diff --git a/doc/gdscript.lyx b/doc/gdscript.lyx new file mode 100644 index 000000000..a4b223012 --- /dev/null +++ b/doc/gdscript.lyx @@ -0,0 +1,2531 @@ +#LyX 2.0 created this file. For more info see http://www.lyx.org/ +\lyxformat 413 +\begin_document +\begin_header +\textclass article +\use_default_options true +\maintain_unincluded_children false +\language english +\language_package default +\inputencoding auto +\fontencoding global +\font_roman default +\font_sans default +\font_typewriter default +\font_default_family default +\use_non_tex_fonts false +\font_sc false +\font_osf false +\font_sf_scale 100 +\font_tt_scale 100 + +\graphics default +\default_output_format default +\output_sync 0 +\bibtex_command default +\index_command default +\paperfontsize default +\use_hyperref false +\papersize default +\use_geometry false +\use_amsmath 1 +\use_esint 1 +\use_mhchem 1 +\use_mathdots 1 +\cite_engine basic +\use_bibtopic false +\use_indices false +\paperorientation portrait +\suppress_date false +\use_refstyle 0 +\index Index +\shortcut idx +\color #008000 +\end_index +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\paragraph_indentation default +\quotes_language english +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\html_math_output 0 +\html_css_as_file 0 +\html_be_strict false +\end_header + +\begin_body + +\begin_layout Title +GD Scripting Language (GDScript) +\end_layout + +\begin_layout Section +Introduction +\end_layout + +\begin_layout Standard +GDScript is a high level, dynamically typed programming language used to + create content. + It uses a syntax that is very similar to the Python language (blocks are + indent-based) and it's goal is to be very optimal and tigthly integrated + with the engine, allowing great flexibility for content creation and integratio +n. + +\end_layout + +\begin_layout Section +Example +\end_layout + +\begin_layout Standard +Some people can learn better by just taking a look at the syntax, so here's + a simple example of how it looks. + +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +#a file is a class! +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#inheritance +\end_layout + +\begin_layout Plain Layout + +extends BaseClass +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#member variables +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +var a=5 +\end_layout + +\begin_layout Plain Layout + +var s="Hello" +\end_layout + +\begin_layout Plain Layout + +var arr=[1,2,3] +\end_layout + +\begin_layout Plain Layout + +var dict={"key":"value", 2:3} +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#constants +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +const answer=42 +\end_layout + +\begin_layout Plain Layout + +const thename="Charly" +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#built-in vector types +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +var v2 = Vector2(1,2) +\end_layout + +\begin_layout Plain Layout + +var v3 = Vector3(1,2,3) +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#function +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +func some_function(param1,param2): +\end_layout + +\begin_layout Plain Layout + + var local_var=5 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + + if param1 < local_var: +\end_layout + +\begin_layout Plain Layout + + print(param1) +\end_layout + +\begin_layout Plain Layout + + elif param2 > 5: +\end_layout + +\begin_layout Plain Layout + + print(param2) +\end_layout + +\begin_layout Plain Layout + + else: +\end_layout + +\begin_layout Plain Layout + + print("fail!") +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + + for i in range(20): +\end_layout + +\begin_layout Plain Layout + + print(i) +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + + while(param2!=0): +\end_layout + +\begin_layout Plain Layout + + param2-=1 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + + var local_var2 = param1+3 +\end_layout + +\begin_layout Plain Layout + + return local_var2 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#subclass +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +class Something: +\end_layout + +\begin_layout Plain Layout + + var a=10 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#constructor +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +func _init(): +\end_layout + +\begin_layout Plain Layout + + print("constructed!") +\end_layout + +\begin_layout Plain Layout + + var lv = Something.new() +\end_layout + +\begin_layout Plain Layout + + print(lv.a) +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Language +\end_layout + +\begin_layout Subsection +Identifiers +\end_layout + +\begin_layout Standard +Any string that restricts itself to alphabetic characters ('a' to 'z' and + 'A' to 'Z'), digits ('0' to '9') and '_' qualifies as an identifier. + As an extra restriction, identifiers must not begin with a digit. + Identifiers are case-sensitive ('foo' is different to 'FOO'). +\end_layout + +\begin_layout Subsection +Keywords +\end_layout + +\begin_layout Standard +The following is the list of keywords supported by the language. + Since keywords are reserved words (tokens), they can't be used as identifiers. +\end_layout + +\begin_layout Subsection +Operators +\end_layout + +\begin_layout Standard +The following is the list of supported operators and their precedence (TODO, + change since this was made to reflect python operators) +\end_layout + +\begin_layout Standard +\begin_inset Tabular +<lyxtabular version="3" rows="18" columns="2"> +<features tabularvalignment="middle"> +<column alignment="center" valignment="top" width="0"> +<column alignment="center" valignment="top" width="0"> +<row> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Operator +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Note +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +x[index] +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Subscription, Highest Priority +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +x.attribute +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Attribute Reference +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +extends +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Instance Type Checker +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +~ +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Bitwise NOT +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +-x +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Negative +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +* / % +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Mult / Div / Remainder +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout ++ - +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Addition / Substraction +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +<< >> +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Bit Shifting +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +& +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Bitwise AND +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +^ +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Bitwise XOR +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +| +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Bitwise OR +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +< > == != >= <= +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Comparisons +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +in +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Content Test +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +! not +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Boolean NOT +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +and && +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Boolean AND +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +or || +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Boolean OR +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout += += -= *= /= ^= &= |= +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Assignment, Lowest Priority +\end_layout + +\end_inset +</cell> +</row> +</lyxtabular> + +\end_inset + + +\end_layout + +\begin_layout Subsection +Literals +\end_layout + +\begin_layout Standard +\begin_inset Tabular +<lyxtabular version="3" rows="6" columns="2"> +<features tabularvalignment="middle"> +<column alignment="center" valignment="top" width="0"> +<column alignment="center" valignment="top" width="0"> +<row> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Literal +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Name +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +45 +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Base 10 Integer +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +0x8F51 +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Base 16 (hex) Integer +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +3.14, 58.1e-10 +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Floating Point Number (real) +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +'Hello', +\begin_inset Quotes eld +\end_inset + +Hi +\begin_inset Quotes erd +\end_inset + + +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Strings +\end_layout + +\end_inset +</cell> +</row> +<row> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +@'Hello', @'Hi' +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Plain Layout +Internationalized Strings +\end_layout + +\end_inset +</cell> +</row> +</lyxtabular> + +\end_inset + + +\end_layout + +\begin_layout Subsection +Comments +\end_layout + +\begin_layout Standard +Anything from a '#' to the end of the line is ignored and is considered + a comment. +\end_layout + +\begin_layout Standard +\begin_inset listings +lstparams "language=Python" +inline false +status open + +\begin_layout Plain Layout + +# This is a comment +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Built-in Types +\end_layout + +\begin_layout Subsection +Basic Bult-In Types +\end_layout + +\begin_layout Standard +A variable in GDScript can be assigned many of several built-in types. + +\end_layout + +\begin_layout Subsubsection +null +\end_layout + +\begin_layout Standard +'null' is a data type that contains no information, nothing assigned, and + it's just empy. + It can only be set to one value: 'null'. +\end_layout + +\begin_layout Subsubsection +bool +\end_layout + +\begin_layout Standard +Boolean data type, can only contain 'true' or 'false'. +\end_layout + +\begin_layout Subsubsection +int +\end_layout + +\begin_layout Standard +Integer data type, can only contain integer numbers, negative and positive. +\end_layout + +\begin_layout Subsubsection +float +\end_layout + +\begin_layout Standard +contains a floating point value (real). +\end_layout + +\begin_layout Subsubsection +String +\end_layout + +\begin_layout Standard +Sequence of characters in unicode format. + Strings can contain the standard C escape sequences. +\end_layout + +\begin_layout Subsection +Vector Built-In Types +\end_layout + +\begin_layout Subsubsection +Vector2/Size2 +\end_layout + +\begin_layout Standard +2D vector type, containing x and y fields. + Can alternatively access fields as width and height for readability. + Can also be accessed as array. +\end_layout + +\begin_layout Subsubsection +Rect2 +\end_layout + +\begin_layout Standard +2D Rectangle type. + Contains 2 vectors fields, +\begin_inset Quotes eld +\end_inset + +pos +\begin_inset Quotes erd +\end_inset + + and size +\begin_inset Quotes erd +\end_inset + +. + Alternatively contains an +\begin_inset Quotes eld +\end_inset + +end +\begin_inset Quotes erd +\end_inset + + field which is +\begin_inset Quotes eld +\end_inset + +pos+size +\begin_inset Quotes erd +\end_inset + +. +\end_layout + +\begin_layout Subsubsection +Vector3 +\end_layout + +\begin_layout Standard +3D vector type. + Contains x, y and z fields. + Can also be accessed as array. +\end_layout + +\begin_layout Subsubsection +Matrix32 +\end_layout + +\begin_layout Standard +3x2 matrix used for 2D transforms. +\end_layout + +\begin_layout Subsubsection +Plane +\end_layout + +\begin_layout Standard +3D Plane type in normalized form. + Contains a +\begin_inset Quotes eld +\end_inset + +normal +\begin_inset Quotes erd +\end_inset + + vector field and a +\begin_inset Quotes eld +\end_inset + +d +\begin_inset Quotes erd +\end_inset + + scalar distance. +\end_layout + +\begin_layout Subsubsection +Quat +\end_layout + +\begin_layout Standard +Quaternion, datatype used for representing a 3D rotation. + It's useful for interpolating rotations. +\end_layout + +\begin_layout Subsubsection +AABB/Box3 +\end_layout + +\begin_layout Standard +Axis Aligned bounding box (or alternatively, 3D box). + Contains 2 vectors fields, +\begin_inset Quotes eld +\end_inset + +pos +\begin_inset Quotes erd +\end_inset + + and size +\begin_inset Quotes erd +\end_inset + +. + Alternatively contains an +\begin_inset Quotes eld +\end_inset + +end +\begin_inset Quotes erd +\end_inset + + field which is +\begin_inset Quotes eld +\end_inset + +pos+size +\begin_inset Quotes erd +\end_inset + +. +\end_layout + +\begin_layout Subsubsection +Matrix3 +\end_layout + +\begin_layout Standard +3x3 matrix used for 3D rotation and scale. + Contains 3 vector fields x,y and z. + Can also be accessed as array of 3D vectors. +\end_layout + +\begin_layout Subsubsection +Transform +\end_layout + +\begin_layout Standard +3D Transform, contains a Matrix3 field +\begin_inset Quotes eld +\end_inset + +basis +\begin_inset Quotes erd +\end_inset + + and a Vector3 field +\begin_inset Quotes eld +\end_inset + +origin +\begin_inset Quotes erd +\end_inset + +. +\end_layout + +\begin_layout Subsection +Engine Built-In Types +\end_layout + +\begin_layout Subsubsection +Color +\end_layout + +\begin_layout Standard +Color datatype, contains r,g,b,a fields. + Can also be accessed as h,s,v for hue/saturation/value. +\end_layout + +\begin_layout Subsubsection +Image +\end_layout + +\begin_layout Standard +Contains a 2D Image of custom format and allows direct access to the pixels. +\end_layout + +\begin_layout Subsubsection +NodePath +\end_layout + +\begin_layout Standard +Compiled path to a node, used mainly in the scene system. + Can be easily asigned from/to a String. +\end_layout + +\begin_layout Subsubsection +RID +\end_layout + +\begin_layout Standard +Resource ID (RID). + Servers use generic RIDs to reference opaque data. +\end_layout + +\begin_layout Subsubsection +Object +\end_layout + +\begin_layout Standard +Base class for anything not a built-in type. + +\end_layout + +\begin_layout Subsubsection +InputEvent +\end_layout + +\begin_layout Standard +Events from input devices are contained in very compact form in InputEvent + objects. + Due to fact they can be received in high amounts from frame to frame, they + are optimized in their own datatype. + +\end_layout + +\begin_layout Subsection +Container Built-In Types +\end_layout + +\begin_layout Subsubsection +Array +\end_layout + +\begin_layout Standard +Generic sequence of objects. + It's size can be changed to anything and starts from index 0. + +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +var arr=[] +\end_layout + +\begin_layout Plain Layout + +arr=[1,2,3] +\end_layout + +\begin_layout Plain Layout + +arr[0]="Hi!" +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Arrays are allocated linearly in memory, so they are fast, but very large + arrays (more than tens of thousands of elements) may cause fragmentation. + There are specialized arrays for some built-in datatypes which do not suffer + from this and use much less memory. +\end_layout + +\begin_layout Subsubsection +Dictionary +\end_layout + +\begin_layout Standard +Associative container which contains values referenced by unique keys. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +var dict={4:5, "a key":"a value", 28:[1,2,3]} +\end_layout + +\begin_layout Plain Layout + +dict["Hi!"]=0 +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +ByteArray +\end_layout + +\begin_layout Standard +Array of bytes. + Can only contains bytes (integers from 0 to 255). + Optimized for memory usage, can't fragment the memory. +\end_layout + +\begin_layout Subsubsection +IntArray +\end_layout + +\begin_layout Standard +Array of integers. + Can only contain integers. + Optimized for memory usage, can't fragment the memory. +\end_layout + +\begin_layout Subsubsection +FloatArray +\end_layout + +\begin_layout Standard +Array of floats, can only contain floats. + Optimized for memory usage, can't fragment the memory. +\end_layout + +\begin_layout Subsubsection +StringArray +\end_layout + +\begin_layout Standard +Array of strings, can only contain strings. + Optimized for memory usage, can't fragment the memory. +\end_layout + +\begin_layout Subsubsection +Vector2Array +\end_layout + +\begin_layout Standard +Array of Vector2, can only contain 2D Vectors. + Optimized for memory usage, can't fragment the memory. +\end_layout + +\begin_layout Subsubsection +Vector3Array +\end_layout + +\begin_layout Standard +Array of Vector3, can only contain 3D Vectors. + Optimized for memory usage, can't fragment the memory. +\end_layout + +\begin_layout Subsubsection +ColorArray +\end_layout + +\begin_layout Standard +Array of Color, can only contains colors. + Optimized for memory usage, can't fragment the memory. +\end_layout + +\begin_layout Section +Data +\end_layout + +\begin_layout Subsection +Variables +\end_layout + +\begin_layout Standard +Variables can exist as class members or local to functions. + They are created with the +\begin_inset Quotes eld +\end_inset + +var +\begin_inset Quotes erd +\end_inset + + keyword and may be, optionally, be assigned a value upon initialization. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +var a # datatype is null by default +\end_layout + +\begin_layout Plain Layout + +var b = 5 +\end_layout + +\begin_layout Plain Layout + +var c = 3.8 +\end_layout + +\begin_layout Plain Layout + +var d = b+c # variables are always initialized in order +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Constants +\end_layout + +\begin_layout Standard +Constants are similar to variables, but must be constants or constant expression +s and must be assigned on initialization. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +const a = 5 +\end_layout + +\begin_layout Plain Layout + +const b = Vector2(20,20) +\end_layout + +\begin_layout Plain Layout + +const c = 10+20 # constant expression +\end_layout + +\begin_layout Plain Layout + +const d = Vector2(20,30).x # constant expression: 20 +\end_layout + +\begin_layout Plain Layout + +const e = [1,2,3,4][0] # constant expression: 1 +\end_layout + +\begin_layout Plain Layout + +const f = sin(20) # sin() can be used in constant expression +\end_layout + +\begin_layout Plain Layout + +const g = x+20 # invalid, not a constant expression! +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Functions +\end_layout + +\begin_layout Standard +Functions always belong to a class. + The scope priority for variable look-up is: local -> class member -> global. + +\begin_inset Quotes eld +\end_inset + +self +\begin_inset Quotes erd +\end_inset + + is provided as an option for accessing class members but is not required + always (and must +\emph on +not +\emph default + be defined as first parameter, like in Python). + For performance reasons, functions are not considered class members, so + they can't be referenced directly. + A function can return at any point. + The default return value is null. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +func myfunction(a,b): +\end_layout + +\begin_layout Plain Layout + + print(a) +\end_layout + +\begin_layout Plain Layout + + print(b) +\end_layout + +\begin_layout Plain Layout + + return a+b # return is optional, otherwise null is returned +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +Statements and Control Flow +\end_layout + +\begin_layout Standard +Statements are standard, and can be assignments, function calls, control + flow structures, etc (see below). + +\begin_inset Quotes eld +\end_inset + +; +\begin_inset Quotes erd +\end_inset + + as separator is entirely optional. +\end_layout + +\begin_layout Subsubsection +if/else/elif +\end_layout + +\begin_layout Standard +Simple conditions are created by using the +\emph on +if/else/elif +\emph default + syntax. + Parenthesis around statements is allowed but not requiered. + Given the nature of the tab-based indentation, elif can be used instead + of else:/if: to mantain a level of indentation. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +if [expression]: +\end_layout + +\begin_layout Plain Layout + + statement(s) +\end_layout + +\begin_layout Plain Layout + +elif [expression]: +\end_layout + +\begin_layout Plain Layout + + statement(s) +\end_layout + +\begin_layout Plain Layout + +else: +\end_layout + +\begin_layout Plain Layout + + statement(s) +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +while +\end_layout + +\begin_layout Standard +Simple loops are created by using +\emph on +while +\emph default + syntax. + Loops can be broken using +\emph on +break +\emph default +, or continued using +\emph on +continue +\emph default +: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +while [expression]: +\end_layout + +\begin_layout Plain Layout + + statement(s) +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +for +\end_layout + +\begin_layout Standard +To iterate a range, array or table a +\emph on +for +\emph default + loop is used. + For loops store the index in the loop variable on each iteration. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +for i in [0,1,2]: +\end_layout + +\begin_layout Plain Layout + + statement # loop iterates 3 times, i being 0,1 and 2 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +var dict = {"a":0, "b":1, "c": 2} +\end_layout + +\begin_layout Plain Layout + +for i in dict: +\end_layout + +\begin_layout Plain Layout + + print(dict[i]) # loop iterates the keys, i being "a","b" and c". + It prints 0, 1 and 2. +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +for i in range(3): +\end_layout + +\begin_layout Plain Layout + + statement # similar to [0,1,2] but does not allocate an array +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +for i in range(1,3): +\end_layout + +\begin_layout Plain Layout + + statement # similar to [1,2] but does not allocate an array +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +for i in range(2,8,2): +\end_layout + +\begin_layout Plain Layout + + statement # similar to [2,4,6] but does not allocate an array +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Classes +\end_layout + +\begin_layout Standard +By default, the body of a script file is an unnamed class, and it can only + be referenced externally as a resource or file. + Class syntax is meant to be very compact and can only contain member variables + or functions. + Static functions are allowed, but not static members (in the spirit of + thread safety, since scripts can be initialized in separate threads without + the user knowing). + In the same way, member variables (including arrays and dictionaries) are + initialized every time an instance is created. + +\end_layout + +\begin_layout Subsection +Class File Example +\end_layout + +\begin_layout Standard +Example of a class file, imagine it being stored in a file like myclass.gd. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +var a=5 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +function print_value_of_a(): +\end_layout + +\begin_layout Plain Layout + + print(a) +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Inheritance +\end_layout + +\begin_layout Standard +A class-file can inherit from a global class, another file or a subclass + inside another file. + Multiple inheritance is not allowed. + The +\begin_inset Quotes eld +\end_inset + +extends +\begin_inset Quotes erd +\end_inset + + syntax is used: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +# extend from some class (global) +\end_layout + +\begin_layout Plain Layout + +extends SomeClass +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +# optionally, extend from another file +\end_layout + +\begin_layout Plain Layout + +extends "somefile.gd" +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +# extend from a subclass in another file +\end_layout + +\begin_layout Plain Layout + +extends "somefile.gd".Subclass +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Inheritance Testing +\end_layout + +\begin_layout Standard +It is possible to check if an instance inherits from a given class. + For this the +\begin_inset Quotes eld +\end_inset + +extends +\begin_inset Quotes erd +\end_inset + + keyword can be used as an operator instead: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +static var enemy_class = preload("enemy.gd") # cache the enemy class +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +[..] +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +if ( entity extends enemy_class ): +\end_layout + +\begin_layout Plain Layout + + entity.apply_damage() +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Constructor +\end_layout + +\begin_layout Standard +A class can have an optional constructor, a function named +\begin_inset Quotes eld +\end_inset + +_init +\begin_inset Quotes erd +\end_inset + + that is called when the class is instanced. +\end_layout + +\begin_layout Subsection +Sub Classes +\end_layout + +\begin_layout Standard +A class file can have subclasses. + Syntax should be straightforward: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +class SomeSubClass: +\end_layout + +\begin_layout Plain Layout + + var a=5 +\end_layout + +\begin_layout Plain Layout + + function print_value_of_a(): +\end_layout + +\begin_layout Plain Layout + + print(a) +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +function _init(): +\end_layout + +\begin_layout Plain Layout + + var sc = SomeSubClass.new() #instance by calling built-in new +\end_layout + +\begin_layout Plain Layout + + sc.print_value_of_a() +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Classes as Objects +\end_layout + +\begin_layout Standard +It may be desired at some point to load a class from a file and then instance + it. + Since the global scope does not exist, classes must be loaded as a resource. + Instancing is done by calling the +\begin_inset Quotes eld +\end_inset + +new +\begin_inset Quotes erd +\end_inset + + function in a class object: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +#load the class (loaded every time the script is instanced) +\end_layout + +\begin_layout Plain Layout + +var MyClass = load("myclass.gd") +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#alternatively, using the preload() function preloads the class at compile + time +\end_layout + +\begin_layout Plain Layout + +var MyClass2 = preload("myclass.gd") +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +function _init(): +\end_layout + +\begin_layout Plain Layout + + var a = MyClass.new() +\end_layout + +\begin_layout Plain Layout + + a.somefunction() +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Exports +\end_layout + +\begin_layout Standard +Class members can be exported. + This means their value gets saved along with a scene. + If class members have initializers to constant expressions, they will be + available for editing in the property editor. + Exporting is done by using the export keyword: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +extends Button +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export var data # value will be saved +\end_layout + +\begin_layout Plain Layout + +export var number=5 # also available to the property editor +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +One of the fundamental benefits of exporting member variables is to have + them visible in the property editor. + This way artists and game designers can modify values that later influence + how the program runs. + For this, a special export syntax is provided for more detail in the exported + variables: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +#if the exported value assigns a constant or constant expression, the type + will be infered and used in the editor +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export var number=5 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#export can take a basic datatype as argument, which will be used in the + editor +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export(int) var number +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#export can also take a resource type as hint +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export(Texture) var character_face +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#integers and strings hint enumerated values +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export(int,"Warrior","Magician","Thief") var character_class # (editor will + set them as 0,1 and 2) +\end_layout + +\begin_layout Plain Layout + +export(String,"Rebecca","Mary","Leah") var character_name +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#strings as paths +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export(String,FILE) var f # string is a path to a file +\end_layout + +\begin_layout Plain Layout + +export(String,DIR) var f # string is a path to a directory +\end_layout + +\begin_layout Plain Layout + +export(String,FILE,"*.txt") var f # string is a path to a file, custom filter + provided as hint +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#integers and floats hint ranges +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export(int,20) var i # 0 to 20 allowed +\end_layout + +\begin_layout Plain Layout + +export(int,-10,20) var j # -10 to 20 allowed +\end_layout + +\begin_layout Plain Layout + +export(float,-10,20,0.2) var k # -10 to 20 allowed, with stepping of 0.2 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +#color can hint availability of alpha +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +export(Color,RGB) var col # Color is RGB +\end_layout + +\begin_layout Plain Layout + +export(Color,RGBA) var col # Color is RGBA +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +It must be noted that even if the script is not being run while at the editor, + the exported properties are still editable (see below for +\begin_inset Quotes eld +\end_inset + +tool +\begin_inset Quotes erd +\end_inset + +). +\end_layout + +\begin_layout Subsection +Static Functions +\end_layout + +\begin_layout Standard +A function can be declared static. + When static, it has no access to the instance member variables or +\begin_inset Quotes eld +\end_inset + +self +\begin_inset Quotes erd +\end_inset + +. + This is mainly useful to make libraries of helper functions: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +static func sum2(a,b): +\end_layout + +\begin_layout Plain Layout + + return a+b +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Asserting +\end_layout + +\begin_layout Standard +It is possible to assert a condition, which will cause a debugger break + if false. + Just use the built-in 'assert' function. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +assert(a==2) +\end_layout + +\begin_layout Plain Layout + +# if a is not 2, it will generate a debugger break +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Tool Mode +\end_layout + +\begin_layout Standard +Scripts by default don't run inside the editor, and only the exported properties + can be changed. + In some cases it is desired that they do (as long as they don't execute + game code or manually avoid doing so). + For this, the +\begin_inset Quotes eld +\end_inset + +tool +\begin_inset Quotes erd +\end_inset + + keyword exists, and must be placed at the top of the file: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +tool +\end_layout + +\begin_layout Plain Layout + +extends Button +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +func _init(): +\end_layout + +\begin_layout Plain Layout + + print("Hello") +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Memory Management +\end_layout + +\begin_layout Standard +If a class inherits from +\emph on +Reference +\emph default +, then instances will be freed when no longer in use. + No garbage collector exists, just simple reference counting. + By default, all classes that don't define inheritance extend +\emph on +Reference +\emph default +. + If this is not desired, then a class must inherit +\emph on +Object +\emph default + manually and must call instance.free(). + To avoid reference cycles that can't be freed, a weakref() function is + provided for creating weak references. + +\end_layout + +\begin_layout Subsection +Function References +\end_layout + +\begin_layout Standard +Functions can't be referenced because they are not treated as class members. + There are two alternatives to this, though. + The +\begin_inset Quotes eld +\end_inset + +call +\begin_inset Quotes erd +\end_inset + + function or the funcref() helper. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +instance.call("funcname",args) # call a function by bane +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +var fr = funcref(instance,"funcname") #create a function ref +\end_layout + +\begin_layout Plain Layout + +fr.exec(args) +\end_layout + +\end_inset + + +\end_layout + +\end_body +\end_document |