diff --git a/advanced.md b/advanced.md new file mode 100644 index 0000000..d7de22d --- /dev/null +++ b/advanced.md @@ -0,0 +1,51 @@ +# Advanced Topics + +## Compiling & Running + + +* [Windows](compiling_windows) Compiling under Windows. + +* [Linux](compiling_linux) Compiling under Linux (or other Unix variants). + +* [OSX](compiling_osx) Compiling under Apple OSX. + +* [Android](compiling_android) Compiling for Android. + +* [iOS](compiling_ios) Compiling for iOS. + +* [QNX](compiling_qnx) Compiling for BlackBerry QNX. + +* [NaCl](compiling_nacl) Compiling for Google Native Client. + +* [Compiler Flags](compiling_flags) General Compiler Flags. + +## File Formats + + +* [XML File](xml_file) XML file format for resources. + +* [Shader File](shader_file) External shader file (.shader). + +* [Theme File](theme_file) External theme (skin) file format. + +* [Config File](engine_cfg) Global engine and project settings file (engine.cfg). + +## Extending the Engine in C++ + + +* [Custom Modules](custom_modules) Creating custom modules in C++. + +* [Resource Loader](add_resource) Adding a new resource loader. + +* [Script Language](add_script_lang) Adding a new scripting language. + +* [Server](add_server) Adding a new server (physics engine, rendering backend, etc). + +* [Platform](add_platform) Porting the engine to a new platform. + +## Misc + + +* [Command Line](command_line) Using the command line, for fans of doing everything in Unix/Windows shell. + +* [External Editor](external_editor) Configuring an external editor for opening scripts. diff --git a/command_line.md b/command_line.md new file mode 100644 index 0000000..3674211 --- /dev/null +++ b/command_line.md @@ -0,0 +1,81 @@ +# Command Line Tutorial + +Some developers like using the command line extensively. Godot is designed to be friendly to them, so here are the steps for working entirely from the command line. Given the engine relies on little to no external libraries, initialization times are pretty fast, making it suitable for this workflow. + +### Path + +It is recommended that your godot binary is in your path, so it can be executed easily from any place by typing "godot". + +### Creating a Project + +Creating a project from the command line is simple, just navigate the shell to the desired place and just make an engine.cfg file exist, even if empty. + +``` + +user@host:~$ mkdir newgame +user@host:~$ cd newgame +user@host:~/newgame$ touch engine.cfg + +``` + +That alone makes for an empty Godot project. + +### Running the Editor + +Running the editor is done by executing godot with the '-e' flag. This must be done from within the project directory, or a subdirectory, otherwise the command is ignored and the project manager appears. + +``` +user@host:~/newgame$ godot -e +``` + +If a scene has been created and saved, it can be edited later by running the same code with that scene as argument. + +``` +user@host:~/newgame$ godot -e scene.xml +``` + +### Erasing a Scene + +Godot is friends with your filesystem, and will not create extra metadata files, simply use ´rm' to erase a file. Make sure nothing references that scene, or else an error will be thrown upon opening. + +``` +user@host:~/newgame$ rm scene.xml +``` + +### Running the Game + +To run the game, simply execute Godot within the project directory or subdirectory. + +``` +user@host:~/newgame$ godot +``` + +When a specific scene needs to be tested, pass that scene to the command line. + +``` +user@host:~/newgame$ godot scene.xml +``` + +### Debugging + +Catching errors in the command line can be a difficult task because they just fly by. For this, a command line debugger is provided by adding '-d'. It works for both running the game or a simple scene. + +``` +user@host:~/newgame$ godot -d +``` + +``` +user@host:~/newgame$ godot -d scene.xml +``` + +### Exporting + +Exporting the project from the command line is also supported. This is specially useful for continuous integration setups. The version of Godot that is headless (no video) is ideal for this. + +``` +user@host:~/newgame$ godot -export Windows /var/builds/project.exe +user@host:~/newgame$ godot -export Android /var/builds/project.apk +``` + + + diff --git a/compiling_android.md b/compiling_android.md new file mode 100644 index 0000000..47d3310 --- /dev/null +++ b/compiling_android.md @@ -0,0 +1,54 @@ +# Note + +For most cases, using the built in deployer and export templates is good enough. Compiling the Android APK manually is mostly useful for custom builds or custom packages for the deployer. + +# Requirements + +For compiling under Windows, the following is requiered: + + +* Python 2.7+ (3.0 is untested as of now). + +* SCons build system. + +* Android SDK version 8 and 13 + +* Android NDK + +# Setting Up SCons + +Set the environment variable ANDROID_HOME to point to the Android SDK. +Set the environment variable ANDROID_NDK_ROOT to point to the Android NDK. + +# Compiling + +Go to the root dir of the engine source code and type: +``` +C:\godot> scons platform/android/libgodot_android.so +``` + +Copy the .so to the libs Android folder (or symlink if you are in Linux or OSX) + +``` +C:\godot> cp platform/android/libgodot_android.so platform/android/java/libs + +alternatively: + +user@host:~/godot$ ln -s platform/android/libgodot_android.so platform/android/java/libs + +``` + +Go to the java folder and run ant + +``` +C:\godot\platform\android\java> ant debug +or +C:\godot\platform\android\java> ant release + +``` + +In the java/bin subfolder, the resulting apk can be used as a custom export template. + +If you intend to simply build the game manually and not use export template, copy or symlink the game content into the java/assets/ folder, so engine.cfg is at the root of java/assets. + + diff --git a/compiling_flags.md b/compiling_flags.md new file mode 100644 index 0000000..ff609da --- /dev/null +++ b/compiling_flags.md @@ -0,0 +1,41 @@ +# General Compiler Flags + +Godot is usually compiled by calling: + +``` + +scons + +``` + +There are a few extra flags that can be used which work in most platforms: + +### Tools + +Tools are added by default. Disabling tools produces a binary that can run projects but that does not include the editor or the project manager. + +``` + +scons tools=yes/no + +``` + +### Target + +Target controls optimization and debug flags. Each mode means: + + +* **debug**: Build with C++ debugging symbols, runtime checks (performs checks and reports error) and none to little optimization. + +* **release_debug**: Build without C++ debugging symbols and optimization, but keep the runtime checks (performs checks and reports errors) + +* **release**: Build without symbols, with optimization and with little to no runtime checks. + + +``` + +scons target=debug/release_debug/release + +``` + + diff --git a/compiling_linux.md b/compiling_linux.md new file mode 100644 index 0000000..138a678 --- /dev/null +++ b/compiling_linux.md @@ -0,0 +1,29 @@ +# Requirements + +For compiling under Linux or other Unix variants, the following is requiered: + + +* GCC or LLVM + +* Python 2.7+ (3.0 is untested as of now). + +* SCons build system. + +* X11 and MESA development Libraries + +* ALSA development libraries + +* Freetype (for the editor) + +* pkg-config (used to detect the above three) + +* **Ubuntu Users:** apt-get install scons pkg-config libx11-dev libxcursor-dev build-essential libasound2-dev libfreetype6-dev libgl1-mesa-dev libglu-dev + +# Compiling + +Start a terminal, go to the root dir of the engine source code and type: +``` +user@host:~/godot$ scons bin/godot +``` + +If all goes well, the resulting binary executable will be placed in the "bin" subdirectory. This executable file contains the whole engine and runs without any dependencies. Executing it will bring up the project manager. diff --git a/compiling_osx.md b/compiling_osx.md new file mode 100644 index 0000000..024878e --- /dev/null +++ b/compiling_osx.md @@ -0,0 +1,20 @@ +# Requirements + +For compiling under Linux or other Unix variants, the following is requiered: + + +* Python 2.7+ (3.0 is untested as of now). + +* SCons build system. + +* XCode + +# Compiling + +Start a terminal, go to the root dir of the engine source code and type: +``` +user@host:~/godot$ scons bin/godot_osx +``` + +If all goes well, the resulting binary executable will be placed in the "bin" subdirectory. This executable file contains the whole engine and runs without any dependencies. Executing it will bring up the project manager. There is a .app template to put the binary into in tools/Godot.app. + diff --git a/compiling_server.md b/compiling_server.md new file mode 100644 index 0000000..69227c8 --- /dev/null +++ b/compiling_server.md @@ -0,0 +1,16 @@ +# Compiling for Unix (Headless) + +### Use Case + + +Godot is mainly used for creating client-side games and applications. However, there are many scenarios where a headless (no display or audio) version might be required, such as: + + +* Automated Scripts (Running single scripts with a specific purpose) + +* Automated Export (Exporting a project for a specific platform, useful for continuous integration) + +* Running a server accepting connections (Godot is perfectly capable of running as a server). + +### Compiling + diff --git a/compiling_windows.md b/compiling_windows.md new file mode 100644 index 0000000..98d2a9a --- /dev/null +++ b/compiling_windows.md @@ -0,0 +1,35 @@ +# Requirements + +For compiling under Windows, the following is requiered: + + +* [Visual C++](http://www.microsoft.com/visualstudio) Visual C++ or Visual C++ Express compiler. + +* [Python 2.7+](http://www.python.org/getit/releases/2.7/) Python 2.7+ (3.0 is untested as of now). Using the 32-bits installer is recommended. + +* [SCons](http://www.scons.org) SCons build system. + +# Setting Up SCons + +Python adds the interpreter (python.exe) to the path. It usually installs in C:\Python (or C:\Python[Version]). SCons installs inside the python install and provides a .bat file called "scons.bat". The location of this file can be added to the path or it can simply be copied to C:\Python together with the interpreter executable. + + +# Compiling + +Start a Visual Studio command prompt (it sets up environment variables needed by SCons to locate the compiler and SDK), go to the root dir of the engine source code and type: +``` +C:\godot> scons bin/godot.exe +``` + +If all goes well, the resulting binary executable will be placed in C:\godot\bin\godot_win.exe. This executable file contains the whole engine and runs without any dependencies. Executing it will bring up the project manager. + +# Development in Visual Studio or other IDEs + +For most projects, using only scripting is enough but when development in C++ is needed, for creating modules or extending the engine, working with an IDE is usually desirable. The visual studio command prompt calls a .bat file that sets up environment variables (vcvarsall.bat). To build the whole engine from a single command outside the command prompt, the following should be called in a .bat file: +``` +C:\path_to_sdk\vcvarsall.bat && scons bin/godot_win.exe +``` + + + + diff --git a/editor_plugin.md b/editor_plugin.md new file mode 100644 index 0000000..f543f66 --- /dev/null +++ b/editor_plugin.md @@ -0,0 +1 @@ +la clase y como hacer undo y redo diff --git a/export.md b/export.md new file mode 100644 index 0000000..12c5b12 --- /dev/null +++ b/export.md @@ -0,0 +1,86 @@ +## Exporting Projects + +### Why Exporting? + +Originally, Godot did not have any means to export projects. The developers would compile the proper binaries and build the packages for each platform manually. + +When more developers (and even non-programmers) started using it, and when our company started taking more projects at the same time, it became evident that this was a bottleneck. + +#### On PC + +Distributing a game project on PC with Godot is rather easy. Just drop the godot.exe (or godot) binary together in the same place as the engine.cfg file, zip it and you are done. This can be taken advantage to make custom installers. + +It sounds simple, but there are probably a few reasons why the developer may not want to do this. The first one is that it may not be desirable to distribute loads of files. Some developers may not like curious users peeking at how the game was made, others may just find it inelegant, etc. + +Another reason is that, for distribution, the developer might use a specially compiled binary, which is smaller in size, more optimized and does not include tools inside (like the editor, debugger, etc). + +Finally, Godot has a simple but efficient system for creating DLCs as extra package files. + +#### On Mobile + +The same scenario in mobile is a little worse. To distribute a project in those devices, a binary for each of those platforms is built, then added to a native project together with the game data. + +This can be troublesome because it means that the developer must be familiarized with the SDK of each platform before even being able to export. In other words, while learning each SDK is always encouraged, it can be frustrating to be forced to do it at an undesired time. + +There is also another problem with this approach, which is the fact that different devices prefer some data in different formats to run. The main example of this is texture compression. All PC hardware uses S3TC (BC) compression and that has been standardized for more than a decade, but mobile devices use different formats for texture compression, such as PVRCT (iOS) or ETC (Android) + +### Export Dialog + +After many attempts at different export workflows, the current one has worked the best.At the time of this writing, not all platforms are supported yet, but that will change soon. + +To open the export dialog, just click the "Export" Button: + +

+ +The dialog will open, showing all the supported export platforms: + +

+ +The default options are often enough to export, so tweaking them is not necessary until it's needed. However, many platforms require additional tools (SDKs) to be installed to be able to export. Additionally, Godot needs exports templates installed to create packages. The export dialog will complain when something is missing and will not allow the user to export for that platform until he or she resolves it: + +

+ +At thas time, the user is expected to come back to the wiki and follow instructions on how to properly set up that platform. + +### Export Templates + +Apart from setting up the platform, the export templates must be installed to be able to export projects. They can be downloaded as a .zip file from the wiki. + +Once downloaded, they can be installed using the "Install Export Templates" option in the editor: + + +

+ +### Export Mode + +When exporting, Godot makes a list of all the files to export and then creates the package. There are 3 different modes for exporting: + + +* Export every single file in the project + +* Export only resources (+custom filter), this is default. + +* Export only selected resources (+custom filter) + +

+ +#### Export every single file + +This mode exports every single file in the project. This is good to test if something is being forgotten, but developers often have a lot of unrelated stuff around in the dev dir, which makes it a bad idea. + +#### Export only resources + +Only resources are exported. For most projects, this is enough. However many developers like to use custom datafiles in their games. To compensate for this, filters can be added for extra extensions (like, *.txt, *.csv, etc). + +#### Export only selected resources + +Only select resources from a list are exported. This is probably overkill for most projects, but in some cases it is justified (usually huge projects). This mode offers total control of what is exported. Individual resources can be selected and dependency detection is performed to ensure that everything needed is added. As a plus, this mode allows to "Bundle" scenes and dependencies into a single file, which is *really* useful for games distributed on optical media. + + +

+ + + + + + diff --git a/export_android.md b/export_android.md new file mode 100644 index 0000000..f8860c0 --- /dev/null +++ b/export_android.md @@ -0,0 +1,47 @@ +## Exporting for Android + +Exporting for android has much less requirements than compiling Godot for it. As follows are the steps to setup the SDK and the engine. + +#### Download the Android SDK + +Download and install the Android SDK from http://developer.android.com/sdk/index.html + +#### Download the Java 6 or OpenJDK6 + +Download and install Java 6 or OpenJDK 6, Android needs this version and it seems that jarsigner (what is used to sign APKs) from greater versions do not work. + +#### Create a debug.keystore + +Android needs a debug keystore file to install to devices and distribute non-release APKs. If you have used the SDK before and have built projects, ant or eclipse probably generated one for you (In Linux and OSX, you can find it in the ~/.android folder). + +If you can't find it or need to generate one, the keytool command from the JDK can be used for this purpose: + +``` +keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999 +``` + +#### Make sure you have adb + +ADB is the command line tool used to communicate with Android devices. It's installed with the SDK, but you may need to install one (any) of the Android API levels for it to be installed in the SDK directory. + +#### Setting it up in Godot + +Enter the Editor Settings screen. This screens contains the editor settings for the user account in the computer (It's independent from the project). + +

+ +Scroll down to the section where the Android settings are located: + +

+ +In that screen, the path to 3 files needs to be set: + + +* The adb executable (adb.exe on Windows) + +* The jarsigner executable (from JDK6) + +* The debug keystore + +Once that is configured, everything is ready to export to Android! + diff --git a/export_ios.md b/export_ios.md new file mode 100644 index 0000000..080995e --- /dev/null +++ b/export_ios.md @@ -0,0 +1,41 @@ +## Exporting for iOS + +Exporting for iOS is done manually at the moment. These are the steps to load your game in an XCode project, where you can deploy to a device, publish, etc. + +#### Requirements + + +* Download XCode for iOS + +* Download the XCode project template: http://www.godotengine.org/builds/release/GodotiOSXCode.zip + +The zip contains an XCode project, "godot_ios.xcodeproj", an empty data.pck file and the engine executable. Open the project, and modify the game name, icon, organization, provisioning signing certificate identities (??), etc. + +#### Add your project data + +Using the Godot editor, [export your project for Windows](export_pc), to obtain the "data.pck" file. Replace the empty data.pck on the XCode project with the new one, and run/archive. + +If you want to test your scenes on the ios device as you edit them, you can add your game directory to the project (instead of data.pck), and add a property "godot_path" to the Info.plist, with the name of your directory as its value. + +{{:godot_path.png|}} + +Alternatively you can add all the files from your game directly, with "engine.cfg" at the root. + +### Loading files from a host + +Sometimes your game becomes too big and deploying to the device takes too long every time you run. In that case you can deploy only the engine executable, and serve the game files from your computer. + +#### Setting up the file host + +On your PC, open the editor, and click the right-most icon on the top-center group of icons, and select "Enable File Server". The icon turns red. Your PC will open a port and accept connections to serve files from your project's directory (so enable your local firewall accordingly). + +{{:rfs_server.png|}} + +#### Setting up the game + +On XCode, click on your app name (top left, next to the "Stop" button), and select "Edit Scheme". Go to the "Arguments" tab, and add 2 arguments, "-rfs" and the IP of your PC. + +{{:edit_scheme.png|}} + +When you run, your device will connect to the host and open the files remotely. Note that the directory with the game data ("platformer") is no longer added to the project, only the engine executable. + diff --git a/export_pc.md b/export_pc.md new file mode 100644 index 0000000..5cf1374 --- /dev/null +++ b/export_pc.md @@ -0,0 +1,15 @@ +## Exporting for PC + +The simplest way to distribute a game for PC is to copy the executables (godot.exe on windows, godot on the rest), zip the folder and send it to someone else. However, this is often not desired. + +Godot offers a more elegant approach for PC distribution when using the export system. When exporting for PC (Linux, Windows, Mac), the exporter takes all the project files and creates a "data.pck" file. This file is bundled with a specially optimized binary that is smaller, faster and lacks tools and debugger. + +Optionally, the files can be bundled inside the executable, though this does not always works properly. + + + + + + + + diff --git a/gdscript.md b/gdscript.md new file mode 100644 index 0000000..e737b87 --- /dev/null +++ b/gdscript.md @@ -0,0 +1,505 @@ +# Introduction + +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 integration. + +# History + +Initially, Godot was designed to support multiple scripting languages (this ability still exists today). However, only GDScript is in use right now. There is a little history behind this. + +In the early days, the engine used the [Lua](http://www.lua.org/) scripting language. Lua is fast, but creating bindings to an object oriented system (by using fallbacks) was complex and slow and took an enormous amount of code. After some experiments with [Python](http://www.python.org/), it also proved difficult to embed. + +The last third party scripting language that was used for shipped games was [Squirrel](http://squirrel-lang.org/), but it was also dropped too. At that point, it became evident that Godot would work more optimally by using a built-in scripting language, as the following barriers were met: + + +* Godot embeds scripts in nodes, most languages are not designed with this in mind. + +* Godot uses several built-in datatypes for 2D and 3D math, script languages do not provide this, and binding them is inefficient. + +* Godot uses threads heavily for lifting and initializing data from the net or disk, script interpreters for common languages are not friendly to this. + +* Godot already has a memory management model for resources, most script languages provide their own, which resulted in duplicate effort and bugs. + +* Binding code is always messy and results in several failure points, unexpected bugs and general unmaintaniability. + +Finally, GDScript was written. The language and interpreter for it ended up being smaller than the binding code itself for Lua and Squirrel, and equally as functional. With time, having a built in language ended up being a huge advantage. + +# Example + +Some people can learn better by just taking a look at the syntax, so here’s a simple example of how it looks. + +```python#a file is a class! + +# inheritance + +extends BaseClass + +# member variables + +var a=5 +var s="Hello" +var arr=[1,2,3] +var dict={"key":"value", 2:3} + +# constants + +const answer=42 +const thename="Charly" + +# built-in vector types + +var v2 = Vector2(1,2) +var v3 = Vector3(1,2,3) + +# function + +func some_function(param1,param2): + var local_var=5 + + if param1 < local_var: + print(param1) + elif param2 > 5: + print(param2) + else: + print("fail!") + + for i in range(20): + print(i) + + while(param2!=0): + param2-=1 + + var local_var2 = param1+3 + return local_var2 + + +# subclass + +class Something: + var a=10 + +# constructor + +func _init(): + print("constructed!") + var lv = Something.new() + print(lv.a) + +#pass + + +func emptyfunc(): + pass # pass does nothing, allows an empty function + +``` + +# Language + +## Identifiers + +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’). + +## Keywords + +The following is the list of keywords supported by the language. Since keywords are reserved words (tokens), they can’t be used as identifiers: + +**and break class const continue elif else enum export extends false for func if in null or pass return self tool true var while** + +## Operators + +The following is the list of supported operators and their precedence (TODO, change since this was made to reflect python operators) + + | Operator | Description | + | -------- | ----------- | + | %%x[index]%% | Subscription, Highest Priority | + | x.attribute | Attribute Reference | + | extends | Instance Type Checker | + | %%~%% | Bitwise NOT | + | -x | Negative | + | * / % | Mult / Div / Remainder | + | + - | Addition / Substraction | + | %%<< >>%% | Bit Shifting | + | & | Bitwise AND | + | %%^%% | Bitwise XOR | + | %% | %% | Bitwise OR | + | %%< > == != >= <=%% | Comparisons | + | in | Content Test | + | %%! not%% | Boolean NOT | + | and && | Boolean AND | + | or %% | | %% | Boolean OR | + | %%= += -= *= /= %= &= | =%% | Assignment, Lowest Priority | + +## Literals + + | Literal | Name | + | ------- | ---- | + | 45 | Base 10 Integer | + | 0x8F51 | Base 16 (hex) Integer | + | 3.14, 58.1e-10 | Floating Point Number (real) | + | ’Hello’, “Hi” | Strings | + | @"Node/Label" | Node Path or StringName | + +## Comments + +Anything from a ’#’ to the end of the line is ignored and is considered a comment. + +```python +# This is a comment``` + +# Built-in Types + +## Basic Bult-In Types + +A variable in GDScript can be assigned many of several built-in types. + +### null + +’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’. + +### bool + +Boolean data type, can only contain ’true’ or ’false’. + +### int + +Integer data type, can only contain integer numbers, negative and positive. + +### float + +contains a floating point value (real). + +### String + +Sequence of characters in unicode format. Strings can contain the standard C escape sequences. + +## Vector Built-In Types + +### Vector2/Size2 + +2D vector type, containing x and y fields. Can alternatively access fields as width and height for readability. Can also be accessed as array. + +### Rect2 + +2D Rectangle type. Contains 2 vectors fields, “pos” and size’’. Alternatively contains an “end” field which is “pos+size”. + +### Vector3 + +3D vector type. Contains x, y and z fields. Can also be accessed as array. + +### Matrix32 + +3x2 matrix used for 2D transforms. + +### Plane + +3D Plane type in normalized form. Contains a “normal” vector field and a “d” scalar distance. + +### Quat + +Quaternion, datatype used for representing a 3D rotation. It’s useful for interpolating rotations. + +### AABB/Box3 + +Axis Aligned bounding box (or alternatively, 3D box). Contains 2 vectors fields, “pos” and size’’. Alternatively contains an “end” field which is “pos+size”. + +### Matrix3 + +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. + +### Transform + +3D Transform, contains a Matrix3 field “basis” and a Vector3 field “origin”. + +## Engine Built-In Types + +### Color + +Color datatype, contains r,g,b,a fields. Can also be accessed as h,s,v for hue/saturation/value. + +### Image + +Contains a 2D Image of custom format and allows direct access to the pixels. + +### NodePath + +Compiled path to a node, used mainly in the scene system. Can be easily asigned from/to a String. + +### RID + +Resource ID (RID). Servers use generic RIDs to reference opaque data. + +### Object + +Base class for anything not a built-in type. + +### InputEvent + +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. + +## Container Built-In Types + +### Array + +Generic sequence of objects. It’s size can be changed to anything and starts from index 0. + +```pythonvar arr=[] +arr=[1,2,3] +arr[0]="Hi!"``` +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 (listed below) for some built-in datatypes which do not suffer from this and use less memory, but they are atomic and generally run a little slower, so they are only justified for very large amount of data. + +### Dictionary + +Associative container which contains values referenced by unique keys. + +```pythonvar d={4:5, "a key":"a value", 28:[1,2,3]} +d["Hi!"]=0 +``` + +Lua-style table syntax is also supported, given it's easier to write and read: + +```python + +var d= { + somekey=2, + otherkey=[2,3,4], + morekey="Hello" +} +``` + +### ByteArray + +Array of bytes. Can only contains bytes (integers from 0 to 255). Optimized for memory usage, can’t fragment the memory. + +### IntArray + +Array of integers. Can only contain integers. Optimized for memory usage, can’t fragment the memory. + +### FloatArray + +Array of floats, can only contain floats. Optimized for memory usage, can’t fragment the memory. + +### StringArray + +Array of strings, can only contain strings. Optimized for memory usage, can’t fragment the memory. + +### Vector2Array + +Array of Vector2, can only contain 2D Vectors. Optimized for memory usage, can’t fragment the memory. + +### Vector3Array + +Array of Vector3, can only contain 3D Vectors. Optimized for memory usage, can’t fragment the memory. + +### ColorArray + +Array of Color, can only contains colors. Optimized for memory usage, can’t fragment the memory. + +# Data + +## Variables + +Variables can exist as class members or local to functions. They are created with the “var” keyword and may be, optionally, be assigned a value upon initialization. + +```pythonvar a # datatype is null by default +var b = 5 +var c = 3.8 +var d = b+c # variables are always initialized in order``` +## Constants + +Constants are similar to variables, but must be constants or constant expressions and must be assigned on initialization. + +```pythonconst a = 5 +const b = Vector2(20,20) +const c = 10+20 # constant expression +const d = Vector2(20,30).x # constant expression: 20 +const e = [1,2,3,4][0] # constant expression: 1 +const f = sin(20) # sin() can be used in constant expression +const g = x+20 # invalid, not a constant expression!``` +## Functions + +Functions always belong to a class. The scope priority for variable look-up is: local -> class member -> global. “self” is provided as an option for accessing class members but is not required always (and must *not* 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. + +```pythonfunc myfunction(a,b): + print(a) + print(b) + return a+b # return is optional, otherwise null is returned``` +### Statements and Control Flow + +Statements are standard, and can be assignments, function calls, control flow structures, etc (see below). “;” as separator is entirely optional. + +### if/else/elif + +Simple conditions are created by using the *if/else/elif* 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. + +```pythonif [expression]: + statement(s) +elif [expression]: + statement(s) +else: + statement(s)``` +### while + +Simple loops are created by using *while* syntax. Loops can be broken using *break*, or continued using *continue*: + +```pythonwhile [expression]: + statement(s)``` +### for + +To iterate a range, array or table a *for* loop is used. For loops store the index in the loop variable on each iteration. + +```pythonfor i in [0,1,2]: + statement # loop iterates 3 times, i being 0,1 and 2 + +var dict = {"a":0, "b":1, "c": 2} +for i in dict: + print(dict[i]) # loop iterates the keys, i being "a","b" and c". It prints 0, 1 and 2. + +for i in range(3): + statement # similar to [0,1,2] but does not allocate an array + +for i in range(1,3): + statement # similar to [1,2] but does not allocate an array + +for i in range(2,8,2): + statement # similar to [2,4,6] but does not allocate an array``` +# Classes + +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. + +## Class File Example + +Example of a class file, imagine it being stored in a file like myclass.gd. + +```pythonvar a=5 + +func print_value_of_a(): + print(a)``` +## Inheritance + +A class-file can inherit from a global class, another file or a subclass inside another file. Multiple inheritance is not allowed. The “extends” syntax is used: + +```python# extend from some class (global) +extends SomeClass + +# optionally, extend from another file + +extends "somefile.gd" + +# extend from a subclass in another file + +extends "somefile.gd".Subclass ``` +## Inheritance Testing + +It is possible to check if an instance inherits from a given class. For this the “extends” keyword can be used as an operator instead: + +```pythonconst enemy_class = preload("enemy.gd") # cache the enemy class + +[..] + +if ( entity extends enemy_class ): + entity.apply_damage()``` +## Constructor + +A class can have an optional constructor, a function named “_init” that is called when the class is instanced. + +## Sub Classes + +A class file can have subclasses. Syntax should be straightforward: + +```pythonclass SomeSubClass: + var a=5 + func print_value_of_a(): + print(a) + +func _init(): + var sc = SomeSubClass.new() #instance by calling built-in new + sc.print_value_of_a()``` +## Classes as Objects + +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 “new” function in a class object: + +```python#load the class (loaded every time the script is instanced) +var MyClass = load("myclass.gd") + +# alternatively, using the preload() function preloads the class at compile time + +var MyClass2 = preload("myclass.gd") + +func _init(): + var a = MyClass.new() + a.somefunction()``` +## Exports + +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: + +```pythonextends Button + +export var data # value will be saved +export var number=5 # also available to the property editor``` +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: + +```python#if the exported value assigns a constant or constant expression, the type will be infered and used in the editor + +export var number=5 + +# export can take a basic datatype as argument, which will be used in the editor + +export(int) var number + +# export can also take a resource type as hint + +export(Texture) var character_face + +# integers and strings hint enumerated values + +export(int,"Warrior","Magician","Thief") var character_class # (editor will set them as 0,1 and 2) +export(String,"Rebecca","Mary","Leah") var character_name + +# strings as paths + +export(String,FILE) var f # string is a path to a file +export(String,DIR) var f # string is a path to a directory +export(String,FILE,"*.txt") var f # string is a path to a file, custom filter provided as hint + +# integers and floats hint ranges + +export(int,20) var i # 0 to 20 allowed +export(int,-10,20) var j # -10 to 20 allowed +export(float,-10,20,0.2) var k # -10 to 20 allowed, with stepping of 0.2 + +# color can hint availability of alpha + +export(Color,RGB) var col # Color is RGB +export(Color,RGBA) var col # Color is RGBA``` +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 “tool”). + +## Static Functions + +A function can be declared static. When static, it has no access to the instance member variables or “self”. This is mainly useful to make libraries of helper functions: + +```pythonstatic func sum2(a,b): + return a+b``` +## Tool Mode + +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 “tool” keyword exists, and must be placed at the top of the file: + +```pythontool +extends Button + +func _init(): + print("Hello")``` +## Memory Management + +If a class inherits from *Reference*, 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 *Reference*. If this is not desired, then a class must inherit *Object* manually and must call instance.free(). To avoid reference cycles that can’t be freed, a weakref() function is provided for creating weak references. + +## Function References + +Functions can’t be referenced because they are not treated as class members. There are two alternatives to this, though. The “call” function or the funcref() helper. + +```pythoninstance.call("funcname",args) # call a function by bane + +var fr = funcref(instance,"funcname") #create a function ref +fr.exec(args)``` + + --- //[Juan Linietsky](reduzio@gmail.com) 2013/11/10 18:09// diff --git a/images/activescene.png b/images/activescene.png new file mode 100644 index 0000000..a9c2b1f Binary files /dev/null and b/images/activescene.png differ diff --git a/images/addedlabel.png b/images/addedlabel.png new file mode 100644 index 0000000..8981047 Binary files /dev/null and b/images/addedlabel.png differ diff --git a/images/addglobal.png b/images/addglobal.png new file mode 100644 index 0000000..f8d7098 Binary files /dev/null and b/images/addglobal.png differ diff --git a/images/addscript.png b/images/addscript.png new file mode 100644 index 0000000..f38fa3d Binary files /dev/null and b/images/addscript.png differ diff --git a/images/addtrack.png b/images/addtrack.png new file mode 100644 index 0000000..164992f Binary files /dev/null and b/images/addtrack.png differ diff --git a/images/anchors.png b/images/anchors.png new file mode 100644 index 0000000..439a96c Binary files /dev/null and b/images/anchors.png differ diff --git a/images/androidsdk.png b/images/androidsdk.png new file mode 100644 index 0000000..97eee25 Binary files /dev/null and b/images/androidsdk.png differ diff --git a/images/animation.png b/images/animation.png new file mode 100644 index 0000000..cfcd8a9 Binary files /dev/null and b/images/animation.png differ diff --git a/images/animedit.png b/images/animedit.png new file mode 100644 index 0000000..2716f25 Binary files /dev/null and b/images/animedit.png differ diff --git a/images/animeditor.png b/images/animeditor.png new file mode 100644 index 0000000..b52ec07 Binary files /dev/null and b/images/animeditor.png differ diff --git a/images/animnew.png b/images/animnew.png new file mode 100644 index 0000000..d79ec48 Binary files /dev/null and b/images/animnew.png differ diff --git a/images/animpanel.png b/images/animpanel.png new file mode 100644 index 0000000..0e470a9 Binary files /dev/null and b/images/animpanel.png differ diff --git a/images/animplayer.png b/images/animplayer.png new file mode 100644 index 0000000..c91e253 Binary files /dev/null and b/images/animplayer.png differ diff --git a/images/autoplay.png b/images/autoplay.png new file mode 100644 index 0000000..c0b5327 Binary files /dev/null and b/images/autoplay.png differ diff --git a/images/bad.png b/images/bad.png new file mode 100644 index 0000000..71a689b Binary files /dev/null and b/images/bad.png differ diff --git a/images/bitmapfont.png b/images/bitmapfont.png new file mode 100644 index 0000000..fc333f1 Binary files /dev/null and b/images/bitmapfont.png differ diff --git a/images/button_connections.png b/images/button_connections.png new file mode 100644 index 0000000..ffd9719 Binary files /dev/null and b/images/button_connections.png differ diff --git a/images/changed.png b/images/changed.png new file mode 100644 index 0000000..ba1e55f Binary files /dev/null and b/images/changed.png differ diff --git a/images/changes.png b/images/changes.png new file mode 100644 index 0000000..945d4ce Binary files /dev/null and b/images/changes.png differ diff --git a/images/chef.png b/images/chef.png new file mode 100644 index 0000000..9b1c034 Binary files /dev/null and b/images/chef.png differ diff --git a/images/compressopts.png b/images/compressopts.png new file mode 100644 index 0000000..0d5c6c3 Binary files /dev/null and b/images/compressopts.png differ diff --git a/images/createnode.png b/images/createnode.png new file mode 100644 index 0000000..725a054 Binary files /dev/null and b/images/createnode.png differ diff --git a/images/ctrl_normal.png b/images/ctrl_normal.png new file mode 100644 index 0000000..84cd5a5 Binary files /dev/null and b/images/ctrl_normal.png differ diff --git a/images/ctrl_tapped.png b/images/ctrl_tapped.png new file mode 100644 index 0000000..eecc758 Binary files /dev/null and b/images/ctrl_tapped.png differ diff --git a/images/edit_scheme.png b/images/edit_scheme.png new file mode 100644 index 0000000..99e14ff Binary files /dev/null and b/images/edit_scheme.png differ diff --git a/images/editor.png b/images/editor.png new file mode 100644 index 0000000..156f138 Binary files /dev/null and b/images/editor.png differ diff --git a/images/editorsettings.png b/images/editorsettings.png new file mode 100644 index 0000000..0731cab Binary files /dev/null and b/images/editorsettings.png differ diff --git a/images/export.png b/images/export.png new file mode 100644 index 0000000..1282cf1 Binary files /dev/null and b/images/export.png differ diff --git a/images/export_dialog.png b/images/export_dialog.png new file mode 100644 index 0000000..3c369ac Binary files /dev/null and b/images/export_dialog.png differ diff --git a/images/export_error.png b/images/export_error.png new file mode 100644 index 0000000..db653ad Binary files /dev/null and b/images/export_error.png differ diff --git a/images/expres.png b/images/expres.png new file mode 100644 index 0000000..fd69a4e Binary files /dev/null and b/images/expres.png differ diff --git a/images/expselected.png b/images/expselected.png new file mode 100644 index 0000000..ad5cd20 Binary files /dev/null and b/images/expselected.png differ diff --git a/images/exptemp.png b/images/exptemp.png new file mode 100644 index 0000000..22568ca Binary files /dev/null and b/images/exptemp.png differ diff --git a/images/fixedborder.png b/images/fixedborder.png new file mode 100644 index 0000000..43a7f66 Binary files /dev/null and b/images/fixedborder.png differ diff --git a/images/fontgradients.png b/images/fontgradients.png new file mode 100644 index 0000000..72a88c6 Binary files /dev/null and b/images/fontgradients.png differ diff --git a/images/fontimport.png b/images/fontimport.png new file mode 100644 index 0000000..8cf3205 Binary files /dev/null and b/images/fontimport.png differ diff --git a/images/fontspacing.png b/images/fontspacing.png new file mode 100644 index 0000000..fa64128 Binary files /dev/null and b/images/fontspacing.png differ diff --git a/images/godot_path.png b/images/godot_path.png new file mode 100644 index 0000000..a4d8e1e Binary files /dev/null and b/images/godot_path.png differ diff --git a/images/good.png b/images/good.png new file mode 100644 index 0000000..1e99a92 Binary files /dev/null and b/images/good.png differ diff --git a/images/groups.png b/images/groups.png new file mode 100644 index 0000000..a57f2e0 Binary files /dev/null and b/images/groups.png differ diff --git a/images/helloworld.png b/images/helloworld.png new file mode 100644 index 0000000..6954426 Binary files /dev/null and b/images/helloworld.png differ diff --git a/images/hw.png b/images/hw.png new file mode 100644 index 0000000..f961079 Binary files /dev/null and b/images/hw.png differ diff --git a/images/import.png b/images/import.png new file mode 100644 index 0000000..f2c56b6 Binary files /dev/null and b/images/import.png differ diff --git a/images/import_images.png b/images/import_images.png new file mode 100644 index 0000000..293fdad Binary files /dev/null and b/images/import_images.png differ diff --git a/images/importaudio.png b/images/importaudio.png new file mode 100644 index 0000000..bbbd945 Binary files /dev/null and b/images/importaudio.png differ diff --git a/images/importdialogs.png b/images/importdialogs.png new file mode 100644 index 0000000..dc5b38f Binary files /dev/null and b/images/importdialogs.png differ diff --git a/images/importtex.png b/images/importtex.png new file mode 100644 index 0000000..570ac82 Binary files /dev/null and b/images/importtex.png differ diff --git a/images/inputmap.png b/images/inputmap.png new file mode 100644 index 0000000..68199c2 Binary files /dev/null and b/images/inputmap.png differ diff --git a/images/isettings.png b/images/isettings.png new file mode 100644 index 0000000..34e2b58 Binary files /dev/null and b/images/isettings.png differ diff --git a/images/keyadded.png b/images/keyadded.png new file mode 100644 index 0000000..26b70e9 Binary files /dev/null and b/images/keyadded.png differ diff --git a/images/keypress.png b/images/keypress.png new file mode 100644 index 0000000..d02a481 Binary files /dev/null and b/images/keypress.png differ diff --git a/images/label.png b/images/label.png new file mode 100644 index 0000000..5f68db6 Binary files /dev/null and b/images/label.png differ diff --git a/images/logo.png b/images/logo.png new file mode 100644 index 0000000..d905ac8 Binary files /dev/null and b/images/logo.png differ diff --git a/images/main_scene.png b/images/main_scene.png new file mode 100644 index 0000000..ed1dbf6 Binary files /dev/null and b/images/main_scene.png differ diff --git a/images/margin.png b/images/margin.png new file mode 100644 index 0000000..1d43911 Binary files /dev/null and b/images/margin.png differ diff --git a/images/marginaround.png b/images/marginaround.png new file mode 100644 index 0000000..67da00a Binary files /dev/null and b/images/marginaround.png differ diff --git a/images/marginend.png b/images/marginend.png new file mode 100644 index 0000000..20b94a6 Binary files /dev/null and b/images/marginend.png differ diff --git a/images/mipmaps.png b/images/mipmaps.png new file mode 100644 index 0000000..375eda2 Binary files /dev/null and b/images/mipmaps.png differ diff --git a/images/move_cursor.png b/images/move_cursor.png new file mode 100644 index 0000000..04dce14 Binary files /dev/null and b/images/move_cursor.png differ diff --git a/images/neversaved.png b/images/neversaved.png new file mode 100644 index 0000000..10de0d7 Binary files /dev/null and b/images/neversaved.png differ diff --git a/images/newnode.png b/images/newnode.png new file mode 100644 index 0000000..5025716 Binary files /dev/null and b/images/newnode.png differ diff --git a/images/newproj.png b/images/newproj.png new file mode 100644 index 0000000..86d81b6 Binary files /dev/null and b/images/newproj.png differ diff --git a/images/newproject.png b/images/newproject.png new file mode 100644 index 0000000..b4a579d Binary files /dev/null and b/images/newproject.png differ diff --git a/images/newscript.png b/images/newscript.png new file mode 100644 index 0000000..5939764 Binary files /dev/null and b/images/newscript.png differ diff --git a/images/nodes_resources.png b/images/nodes_resources.png new file mode 100644 index 0000000..036ae10 Binary files /dev/null and b/images/nodes_resources.png differ diff --git a/images/nodesearch.png b/images/nodesearch.png new file mode 100644 index 0000000..923886b Binary files /dev/null and b/images/nodesearch.png differ diff --git a/images/oneclick.png b/images/oneclick.png new file mode 100644 index 0000000..d4adf56 Binary files /dev/null and b/images/oneclick.png differ diff --git a/images/playscene.png b/images/playscene.png new file mode 100644 index 0000000..af26018 Binary files /dev/null and b/images/playscene.png differ diff --git a/images/pong_layout.png b/images/pong_layout.png new file mode 100644 index 0000000..060738f Binary files /dev/null and b/images/pong_layout.png differ diff --git a/images/pong_nodes.png b/images/pong_nodes.png new file mode 100644 index 0000000..0d1c6ef Binary files /dev/null and b/images/pong_nodes.png differ diff --git a/images/propertykeys.png b/images/propertykeys.png new file mode 100644 index 0000000..11a5a36 Binary files /dev/null and b/images/propertykeys.png differ diff --git a/images/regular.png b/images/regular.png new file mode 100644 index 0000000..4ffb148 Binary files /dev/null and b/images/regular.png differ diff --git a/images/reimported.png b/images/reimported.png new file mode 100644 index 0000000..32c03e0 Binary files /dev/null and b/images/reimported.png differ diff --git a/images/resourcerobi.png b/images/resourcerobi.png new file mode 100644 index 0000000..f03d24a Binary files /dev/null and b/images/resourcerobi.png differ diff --git a/images/reverb.png b/images/reverb.png new file mode 100644 index 0000000..e37eb9f Binary files /dev/null and b/images/reverb.png differ diff --git a/images/rfs_server.png b/images/rfs_server.png new file mode 100644 index 0000000..fa07e5a Binary files /dev/null and b/images/rfs_server.png differ diff --git a/images/robisplashpreview.png b/images/robisplashpreview.png new file mode 100644 index 0000000..b218689 Binary files /dev/null and b/images/robisplashpreview.png differ diff --git a/images/robisplashscene.png b/images/robisplashscene.png new file mode 100644 index 0000000..a6d4078 Binary files /dev/null and b/images/robisplashscene.png differ diff --git a/images/saveasscript.png b/images/saveasscript.png new file mode 100644 index 0000000..d4503bc Binary files /dev/null and b/images/saveasscript.png differ diff --git a/images/savescene.png b/images/savescene.png new file mode 100644 index 0000000..0f63482 Binary files /dev/null and b/images/savescene.png differ diff --git a/images/scene.png b/images/scene.png new file mode 100644 index 0000000..0b57b41 Binary files /dev/null and b/images/scene.png differ diff --git a/images/script_template.png b/images/script_template.png new file mode 100644 index 0000000..d3c9d66 Binary files /dev/null and b/images/script_template.png differ diff --git a/images/scriptadded.png b/images/scriptadded.png new file mode 100644 index 0000000..1656bf2 Binary files /dev/null and b/images/scriptadded.png differ diff --git a/images/scriptcreate.png b/images/scriptcreate.png new file mode 100644 index 0000000..bbac9e2 Binary files /dev/null and b/images/scriptcreate.png differ diff --git a/images/scripthello.png b/images/scripthello.png new file mode 100644 index 0000000..d0e5874 Binary files /dev/null and b/images/scripthello.png differ diff --git a/images/scriptscene.png b/images/scriptscene.png new file mode 100644 index 0000000..28fdff5 Binary files /dev/null and b/images/scriptscene.png differ diff --git a/images/scriptsceneimg.png b/images/scriptsceneimg.png new file mode 100644 index 0000000..d2abdea Binary files /dev/null and b/images/scriptsceneimg.png differ diff --git a/images/shadowoutline.png b/images/shadowoutline.png new file mode 100644 index 0000000..67e4bcb Binary files /dev/null and b/images/shadowoutline.png differ diff --git a/images/signals.png b/images/signals.png new file mode 100644 index 0000000..455f250 Binary files /dev/null and b/images/signals.png differ diff --git a/images/singlecontrol.png b/images/singlecontrol.png new file mode 100644 index 0000000..3fa5621 Binary files /dev/null and b/images/singlecontrol.png differ diff --git a/images/singleton.png b/images/singleton.png new file mode 100644 index 0000000..cf1b112 Binary files /dev/null and b/images/singleton.png differ diff --git a/images/spriteprop.png b/images/spriteprop.png new file mode 100644 index 0000000..525b451 Binary files /dev/null and b/images/spriteprop.png differ diff --git a/images/texbutton.png b/images/texbutton.png new file mode 100644 index 0000000..502444c Binary files /dev/null and b/images/texbutton.png differ diff --git a/images/texframe.png b/images/texframe.png new file mode 100644 index 0000000..ceb988d Binary files /dev/null and b/images/texframe.png differ diff --git a/images/toptobottom.png b/images/toptobottom.png new file mode 100644 index 0000000..16bde44 Binary files /dev/null and b/images/toptobottom.png differ diff --git a/images/trans.png b/images/trans.png new file mode 100644 index 0000000..047b3da Binary files /dev/null and b/images/trans.png differ diff --git a/images/tree.png b/images/tree.png new file mode 100644 index 0000000..c923d60 Binary files /dev/null and b/images/tree.png differ diff --git a/images/trim.png b/images/trim.png new file mode 100644 index 0000000..15d09f2 Binary files /dev/null and b/images/trim.png differ diff --git a/import_fonts.md b/import_fonts.md new file mode 100644 index 0000000..5cbe7f6 --- /dev/null +++ b/import_fonts.md @@ -0,0 +1,63 @@ +## Importing Fonts + +### What is a Font? + +Fonts in modern operating systems are created as scalable vector graphics. They are stored as a collection of curves (usually one for each character), which are independent of the screen resolution, and stored in standardized file formats, such as TTF (TrueType) or OTF (OpenType). + +Rendering such fonts to bitmaps is a complex process, which employs different methods to convert curves to pixels depending on context and target size. Due to this, this rendering process must be done by using the CPU. +Game engines use the GPU to render, and 3D APIs don't really support the means to do this efficiently, so fonts have to be converted to a format that is friendly to the GPU when imported to a project. + +### Converting Fonts + +This conversion process consists of rendering a vector font to a given point size and storing all the resulting characters in a bitmap texture. The bitmap texture is then used by the GPU to draw a small quad for each character and form readable strings. + +

+ +The drawback of this process is that fonts must be pre-imported in the specific sizes that they will use in the project. However, given that that bitmap fonts compress really well, this is not as bad as it sounds. + +### Importing a Font + +Fonts are imported via the Font import dialog. The dialog will ask for a font, a size, some options and a target resource fie to save. + +

+ +The dialog is fully dynamic, which means that any change will be reflected in the font preview window. The user ccan tweak almost every parameter and get instant feedback on how the font will look. + +Since the resulting font is a bitmap, a few more options were added to make the imported font look even nicer. These options were added to please graphic designers, who love putting gradients, outlines and shadows in fonts, as well as changing all the inter-spaces available :). The options which will be explained as follows. + +#### Extra Spacing + +It is possible to add more space for: + +* Characters, the space between them can be varied. + +* "space" character, so the distance between words is bigger. + +* Top and Bottom margins, this changes the spacing between lines as well as the space between the top and bottom lines and the borders. + +

+ +#### Shadows & Outline + +Fonts can be added a shadow. For this, the font is drawn again below on a different color and the blurred with a gaussian kernel of different sizes. The resulting shadow can be adjusted with an exponential function to make it softer or more like an outline. A second shadow is also provided to create some added effects, like a bump or outline+shadow. + +

+ +#### Gradients + +Gradients are also another of the visual effects that graphic designers often use. To show how much we love them, we added those too. Gradients can be provided as a simple curve between two colors, or a special png file with a hand drawn gradient. + +

+ +#### Internationalization + +Colors, shadows and gradients are beautiful, but it's time we get to serious business. Developing games for Asian markets is a common practice in today's globalized world and app stores. + +Here's when things get tricky with using bitmap fonts. Asian alphabets (Chinese, Japanese and Korean) contains dozens of thousands of characters. Generating bitmap fonts with every single of them is pretty expensive, as the resulting textures are huge. If the font size is small enough, it can be done without much trouble, but when the fonts become bigger, we run out of video ram pretty quickly! + +To solve this, Godot allows the user to specify a text file (in UTF-8 format) where it expects to find all the characters that will be used in the project. This seems difficult to provide at first, and more to keep up to date, but it becomes rather easy when one realizes that the .csv with the translations can be used as such source file (see the [Importing Translations](import_translations) section). As Godot re-imports assets when their dependencies change, both the translation and font files will be updated and re-imported automatically if the translation csv changes. + +Another cool trick for using a text file as limit of which characters can be imported is when using really large fonts. For example, the user might want to use a super large font, but only to show numbers. For this, he or she writes a numbers.txt file that contains "1234567890", and Godot will only limit itself to import data, thus saving a lot of video memory. + + + --- //[Juan Linietsky](reduzio@gmail.com) 2013/11/10 18:12// diff --git a/import_process.md b/import_process.md new file mode 100644 index 0000000..a552e46 --- /dev/null +++ b/import_process.md @@ -0,0 +1,93 @@ +## The Import Process + +### What is it for? + +When Godot was created, it was probably after several failed and not so failed engine attempts (well, each attempt failed a little less.. and so on). One of the most difficult areas of creating game engines is managing the import process. That means, getting the assets that artists make into the game, in a way that functions optimally. + +Artists use certain tools and formats, and programmers would rather have their data into a different format. This is because artists put their focus on creating assets with the best quality possible, while programmers have to make sure they actually run at decent speed (or run at all), use a certain amount of memory, and don't take ages loading from disk. + +One would think that just writing a converter/importer would be enough, but this is not all there is to it. The same way programmers iterate several times over their code, artists keep making changes to their assets. This generates some bottleneck, because *someone* has to keep re-importing that artwork right? And importing assets is often something that has to be agreed by both parties, as the programmer needs to decide how the artwork is imported and the artists needs to see how it looks. + +The goal to establishing an import process is that both can agree on how the rules under which the assets are going to be imported the first time, and the system will apply those rules automatically each time the asset is re-imported. + +Godot does not do the re-import process automatically, though. It gives the team the option to do it at any time ( a red icon on the top right of the screen, allows the ability to do it at any desired time). + +### Does it Always Work? + +The aim of the import system is that it works well enough for most common cases and projects. What is there has been tested and seems to cover most needs. + +However, as mentioned before, this is on of the most difficult areas of writing a game engine. It may happen often (specially on large projects, ports, or projects with unusual requirement) that what is provided is not enough. It's easy to say that the engine is open source and that the programmer should make their own if they don't like what is there, but that would be making a huge disservice to the users and not the right attitude. Because of that, we made sure to provide as many tools and helpers as possible to support a custom import process, for example: + + +* Access to the internals of almost all data structures is provided to the scripting and C++ API, as well as saving and loading in all supported file formats. + +* Some importers (like the 3D asset importer) support scripts to modify the data being imported. + +* Support for creating custom import plugins is also provided, even for replacing the existing ones. + +* If all else fails, Godot supports for adding custom resource loaders, to load data in alternative formats, without intermediate conversion. + +Both the import system and the custom tools provided will improve over time as more use cases are revealed to us. + +### Importing Assets + +#### Source Asset Location + +To begin, it is a good idea to define where the original assets created by the artists (before they are imported) will be located. Normally, Godot does not mind much about the location, but if the project has several developers, it is a good idea to understand the simple rule for it to work for everyone. + +First of all, it would be really good for this location to **not** be inside the project path (where engine.cfg is located, or any sub-folder). Godot expects regular resources in there, and may consider many of the files used as source art as regular resources. This would lead to it bundling all of them when the project is exported, something which is undesired. + +Now that it is clear that this location must be outside the project folder, the rule that Godot uses to reference external assets can be explained. When an asset is imported, the engine stores a relative path from the project path to the asset (In windows, this works as long as they are on the same drive, otherwise an absolute path is stored). This ensures that the same asset can be re-imported in another computer. + +The usual approach to this, when using a VCS such as Subversion, Perforce or GIT, is to create the project in a subfolder, so both it and the source assets can be commited to a same repository. For example: + +``` + +Repository Layout: + +source_assets/sfx/explosion.wav +source_assets/sfx/crash.wav +source_assets/fonts/myfont.ttf +source_assets/translation/strings.csv +source_assets/art/niceart.psd +game/engine.cfg + +``` + +In the above example, artists, musican, translators, etc. can work in the source_assets/ folder, then import the assets to the game/ folder. When the repository is updated, anyone can re-import the assets if they changed. + +#### Import Dialogs + +Godot provides for importing several types of assets, all of them can be accessed from the import dialog: + +

+ +Each of the dialog shares a similar function, a source file (or several of them) must be provided, as well as a target destination inside the project folders. Once imported, Godot saves this information as metadata in the imported asset itself. + +

+ +More information about each specific type of asset can be found in specific sections, such as [Importing Textures](import_textures). + +#### Tracking Changes and Re-Importing + +Godot tracks changes in the source assets constantly. If at least one asset has been found to be modified (md5 is different than when it was imported), a small red indicator will appear in the top right corner of the screen. + +

+ +From that moment onward, the user can choose to re-import at any given time by clicking on the red-icon. When this action is done, a dialog will pop-up showing which resources can be re-imported (all selected by default). +Accepting that dialog will immediately re-import the resources and will update any of them currently in use in the editor (like a texture, model or audio file). + +

+ +#### Manually Re-Import + +The re-import process is automatic, but it may be desired at some point to change the settings of an already imported file, so it can be re-imported differently. For this, the Import Settings window is provided. + +

+ +This screen allows the user to re-open the corresponding import-window to re-import that asset again, with the ability to change any of the settings. + +

+ + --- //[Juan Linietsky](reduzio@gmail.com) 2013/11/10 18:11// + diff --git a/import_samples.md b/import_samples.md new file mode 100644 index 0000000..c802324 --- /dev/null +++ b/import_samples.md @@ -0,0 +1,51 @@ +## Importing Audio Samples + +#### Why Importing? + +Importing Audio Samples into the game engine is a process that should be easier than it really is. Most readers are probably thinking "Why not just copying the .wav files to a folder inside the project and be over with it?". + +It's not usually that simple. Most game engines use uncompressed audio (in memory at least) for sound effects. The reason for this is because it's really cheap to play back and resample. Compressed streamed audio (such as .ogg files) takes a large amount of processor to decode so no more than one or two are streamed simultaneously. However, with sound effects, one expects a dozen of them to be playing at the same time in several situations. + +Because of this, sound effects are loaded uncompressed into memory, and here is where the problems begin. + +As is usual with graphics, the situation where programmers don't really know about audio and audio engineers don't know about programming is also common in the industry. This leads to a scenario where a project ends up wasting resources unnecessarily. + +To be more precise, sfx artists tend to work with audio formats that give them a lot of room for tweaking the audio with a low noise floor minimum aliasing, such as 96khz, 24 bits. In many cases, they work in stereo too. +Added to that, many times they add effects with an infinite or really long fadeout, such as reverb, which take a long time to fade out. Finally, many DAWs also add silence at the beginning when normalizing to wav. + +This results in extremely large files to integrate more often than desired, with sound effects taking dozens of megabytes. + +#### How Much does Quality Matter? + +First of all, it is important to know that Godot has an internal reverb generator. Sound effects can go to four different setups (small, medium and large room as well as hall), with different send amounts. This saves sfx artists the need to add reverb to the sound effects, reducing their size greatly and ensuring correct trimming. Say no to SFX wit baked reverb! + +

+ +Another common problem is that, while it's useful for working inside a DAW, high dynamic range (24 bits) and high sampling rate (96khz) is completely unnecessary for use in a game, as there is no [audible difference](http://www.youtube.com/watch?v=cIQ9IXSUzuM). If positional sound is going to be used (for 2D and 3D), the panning and stereo reverb will be provided by the engine, so there is little need for stereo sound. How does this affect the resource usage? Look at the following comparison: + + | Format | 1 Second of Audio | Frame Size | + | ------ | ----------------- | ---------- | + | 24 bits, 96 khz, Stereo | 576kb | 6 | + | 16 bits, 44 khz, Mono | 88kb | 2 | + +As seen, for being no audible difference, the 16 bits, 44khz takes *6 times less memory* than the 24 bits, 96khz, Stereo version. + +#### Trimming + +One last issue that happens often is that the waveform files received have silences at the beginning and at the end. These are inserted by DAWs when saving to a waveform, increase their size unnecessarily and add latency to the moment they are played back. Trimming them solves this, but it takes effort for the sfx artist, as they have to do it in a separate application. In the worst case, they may not even know the silences are being added. +

+#### Importing Audio Samples + +Godot has a simple screen for importing audio samples to the engine. SFX artists only have to save the .wav files to a folder outside the project, and the import dialog will fix the files for inclusion, as well as doing it automatically every time they are modified and re-imported. + +

+ +In this screen, the quality of the audio can be limited to what is needed, and trimming is done automatically. As a plus, several samples can be loaded and batch-converted, just like textures. + +#### Looping + +Godot supports looping in the samples (Tools such as Sound Forge or Audition can add loop points to .wav files). This is useful for sound effects such as engines, machine guns, etc. Ping-Pong looping is also supported. + +As an alternative, the import screen has a "loop" option that enables looping for the entire sample when importing. + + --- //[Juan Linietsky](reduzio@gmail.com) 2013/11/10 18:13// diff --git a/import_textures.md b/import_textures.md new file mode 100644 index 0000000..5ded36c --- /dev/null +++ b/import_textures.md @@ -0,0 +1,158 @@ +# Importing Textures + +## Rationale + + +### What For? + +Godot can work with images directly on the filesystem and open them just like any other resource. So the first issue that comes to mind is.. is it worth it? When developing 2D games specially, there's no denying that having the image files around in the filesystem in their standard formats (png, jpg, etc) is nice and useful. + +Still, there are many advantages to using the texture importer. For 3D it's done automatically when importing models, but in 2D it must be done by hand. The following sections will illustrate scenarios for using the texture importer. + +### Do it Later.. + +Remember that by default, Godot ignores the extension of the referenced files. this allows to replace the images in standard formats by engine .tex files at a later time and nothing is lost. + +## Common Problems + +Several problems arise from trying to use standard image formats: + +### Lack of MipMaps + +Images in 3D hardware are scaled with a (bi)linear filter, but this method has limitations. When images are shrunk too much, two problems arise: + +* __Aliasing__: Pixels are skipped too much, and the image shows discontinuities. This decrases quality. + +* __Cache Misses__: Pixels being read are too far apart, so texture cache reads a lot more data than it should. This decreases performance. + +(Todo, find image sample of why it looks bad) + +To solve this, mipmaps are created. Mipmaps are versions of the image shrunk by half in both axis, recursively, until the image is 1 pixel of size. When the 3D hardware needs to shrink the image, it finds the largest mipmap it can scale from, and scales from there. This improves performance and image quality. +

=Best,

=Worst): + + | | Uncompressed | Compress Lossless (PNG) | Compress Lossy (WebP) | Compress VRAM | + | | ------------ | ----------------------- | --------------------- | ------------- | + | Description | Stored as raw pixels | Stored as PNG | Stored as WebP | Stored as S3TC/BC,PVRTC/ETC, depending on platform| + | Size on Disk | {{:bad.png|}}Large |

Small |

Very Small |

Small | + | Memory Usage | {{:bad.png|}}Large | {{:bad.png|}}Large | {{:bad.png|}}Large |

Small | + | Performance |

Normal |

Normal |

Normal |

Fast | + | Quality Loss |

None |

None |

Slight | {{:bad.png|}}Moderate | + | Load Time |

Normal | {{:bad.png|}}Slow | {{:bad.png|}}Slow |

Fast | + + +### Texture Options: + +Provided are a small amount of options for fine grained import control: + +#### Streaming Format + +This does nothing as of yet, but a texture format for streaming different mipmap levels is planned. Big engines have support for this. + +#### Fix Border Alpha + +This will fix texture borders to avoid the white auras created by white invisible pixels (see the rant above). + +#### Alpha Bit Hint + +Godot auto-detects if the texture needs alpha bit support for transparency (instead of full range), which is useful for compressed formats such as BC. This forces alpha to be 0 or 1. + +#### Compress Extra + +Some VRAM compressions have alternate formats that compress more at the expense of quality (PVRTC2 for example). If this is ticked, texture will be smaller but look worse. + +#### No MipMaps + +Force imported texture to NOT use mipmaps. This may be desirable in some cases for 2D (as explained in the rant above), though it's NEVER desirable for 3D. + +#### Repeat + +Texture will repeat when UV coordinates go beyond 1 and below 0. This is often desirable in 3D, but may generate artifacts in 2D. + +#### Filter + +Enables linear filtering when a texture texel is larger than a screen pixel. This is usually turned on, unless it's required for artistic purposes (minecraft look, for example). + + + --- //[Juan Linietsky](reduzio@gmail.com) 2013/11/10 18:11// diff --git a/import_translation.md b/import_translation.md new file mode 100644 index 0000000..58729b1 --- /dev/null +++ b/import_translation.md @@ -0,0 +1,45 @@ +## Importing Translations + +#### Games and Internationalization + +The world is full of different markets and cultures and, to maximize profits(tm), nowadays games are released in several languages. To solve this, internationalized text must be supported in any modern game engine. + +In regular desktop or mobile applications, internationalized text is usually located in resource files (or .po files for GNU stuff). Games, however, can use several orders of magnitude more text than applications, so they must support efficient methods for dealing with loads of multi-language text. + +There are two approaches to generate multi language games and applications. Both are based on a key:value system. The first is to use one of the languages as key (usually english), the second is to use a specific identifier. The first approach is probably easier for development if a game is released first in english, later in other languages, but a complete nightmare if working with many languages at the same time. + +In general, games use the second approach and a unique ID is used for each string. This allows to revise the text while it's being translated to others. the unique ID can be a number, a string, or a string with a number (it's just a unique string anyway). + +Translators also, most of the time prefer to work with spreadsheets (either as a Microsoft Excel file or a shared Google Spreadsheet). + +#### Translation Format + +To complete the picture and allow efficient support for translations, Godot has a special importer that can read .csv files. Both Microsoft Excel and Google Spreadsheet can export to this format, so the only requirement is that the files have a special format. The csv files must be saved in utf-8 encoding and the format is as follows: + + | | %%%% | %%%% | %%%% | + | | ----------- | ----------- | ----------- | + | KEY1 | %%string%%| %%string%%|%%string%%| + | KEY2 | %%string%%| %%string%%|%%string%%| + | KEYN | %%string%%| %%string%%|%%string%%| + +The "lang" tags must represent a language, it must be one of the [valid locales](locales) supported by the engine. The "KEY" tags must be unique and represent a string universally (they are usually in uppercase, to differentiate from other strings). Here's an example: + + + | | en | es | ja | + | | -- | -- | -- | + | GREET | Hello, friend! | Hola, Amigo!|こんにちは| + | ASK | How are you?| Cómo esta?|元気ですか| + | BYE | Good Bye| Adiós|さようなら| + +#### Import Dialog + +The import dialog takes a .csv file in the previously described format and generates several compressed translation resource files inside the project. + +Selecting a .csv file autodetects the languages from the first row. and determines which column represents which language. It is possible to change that manually, by selecting the language for each column. + +

+ +The import dialog also can add the translation to the list of translations to load when the game runs, specified in engine.cfg (or the project properties). Godot allows to load and remove translations at runtime, too. + + --- //[Juan Linietsky](reduzio@gmail.com) 2013/11/10 21:42// + diff --git a/locales.md b/locales.md new file mode 100644 index 0000000..1b7d0e2 --- /dev/null +++ b/locales.md @@ -0,0 +1,160 @@ +# Supported Locales + +This is the list of supported locales and variants in the engine. It's based on the Unix standard locale strings: + + | Locale | Language and Variant | + | ------ | -------------------- | + | ar | Arabic | + | ar_AE | Arabic (United Arab Emirates) | + | ar_BH | Arabic (Bahrain) | + | ar_DZ | Arabic (Algeria) | + | ar_EG | Arabic (Egypt) | + | ar_IQ | Arabic (Iraq) | + | ar_JO | Arabic (Jordan) | + | ar_KW | Arabic (Kuwait) | + | ar_LB | Arabic (Lebanon) | + | ar_LY | Arabic (Libya) | + | ar_MA | Arabic (Morocco) | + | ar_OM | Arabic (Oman) | + | ar_QA | Arabic (Qatar) | + | ar_SA | Arabic (Saudi Arabia) | + | ar_SD | Arabic (Sudan) | + | ar_SY | Arabic (Syria) | + | ar_TN | Arabic (Tunisia) | + | ar_YE | Arabic (Yemen) | + | be | Belarusian | + | be_BY | Belarusian (Belarus) | + | bg | Bulgarian | + | bg_BG | Bulgarian (Bulgaria) | + | ca | Catalan | + | ca_ES | Catalan (Spain) | + | cs | Czech | + | cs_CZ | Czech (Czech Republic) | + | da | Danish | + | da_DK | Danish (Denmark) | + | de | German | + | de_AT | German (Austria) | + | de_CH | German (Switzerland) | + | de_DE | German (Germany) | + | de_LU | German (Luxembourg) | + | el | Greek | + | el_CY | Greek (Cyprus) | + | el_GR | Greek (Greece) | + | en | English | + | en_AU | English (Australia) | + | en_CA | English (Canada) | + | en_GB | English (United Kingdom) | + | en_IE | English (Ireland) | + | en_IN | English (India) | + | en_MT | English (Malta) | + | en_NZ | English (New Zealand) | + | en_PH | English (Philippines) | + | en_SG | English (Singapore) | + | en_US | English (United States) | + | en_ZA | English (South Africa) | + | es | Spanish | + | es_AR | Spanish (Argentina) | + | es_BO | Spanish (Bolivia) | + | es_CL | Spanish (Chile) | + | es_CO | Spanish (Colombia) | + | es_CR | Spanish (Costa Rica) | + | es_DO | Spanish (Dominican Republic) | + | es_EC | Spanish (Ecuador) | + | es_ES | Spanish (Spain) | + | es_GT | Spanish (Guatemala) | + | es_HN | Spanish (Honduras) | + | es_MX | Spanish (Mexico) | + | es_NI | Spanish (Nicaragua) | + | es_PA | Spanish (Panama) | + | es_PE | Spanish (Peru) | + | es_PR | Spanish (Puerto Rico) | + | es_PY | Spanish (Paraguay) | + | es_SV | Spanish (El Salvador) | + | es_US | Spanish (United States) | + | es_UY | Spanish (Uruguay) | + | es_VE | Spanish (Venezuela) | + | et | Estonian | + | et_EE | Estonian (Estonia) | + | fi | Finnish | + | fi_FI | Finnish (Finland) | + | fr | French | + | fr_BE | French (Belgium) | + | fr_CA | French (Canada) | + | fr_CH | French (Switzerland) | + | fr_FR | French (France) | + | fr_LU | French (Luxembourg) | + | ga | Irish | + | ga_IE | Irish (Ireland) | + | hi | Hindi (India) | + | hi_IN | Hindi (India) | + | hr | Croatian | + | hr_HR | Croatian (Croatia) | + | hu | Hungarian | + | hu_HU | Hungarian (Hungary) | + | in | Indonesian | + | in_ID | Indonesian (Indonesia) | + | is | Icelandic | + | is_IS | Icelandic (Iceland) | + | it | Italian | + | it_CH | Italian (Switzerland) | + | it_IT | Italian (Italy) | + | iw | Hebrew | + | iw_IL | Hebrew (Israel) | + | ja | Japanese | + | ja_JP | Japanese (Japan) | + | ja_JP_JP | Japanese (Japan,JP) | + | ko | Korean | + | ko_KR | Korean (South Korea) | + | lt | Lithuanian | + | lt_LT | Lithuanian (Lithuania) | + | lv | Latvian | + | lv_LV | Latvian (Latvia) | + | mk | Macedonian | + | mk_MK | Macedonian (Macedonia) | + | ms | Malay | + | ms_MY | Malay (Malaysia) | + | mt | Maltese | + | mt_MT | Maltese (Malta) | + | nl | Dutch | + | nl_BE | Dutch (Belgium) | + | nl_NL | Dutch (Netherlands) | + | no | Norwegian | + | no_NO | Norwegian (Norway) | + | no_NO_NY | Norwegian (Norway,Nynorsk) | + | pl | Polish | + | pl_PL | Polish (Poland) | + | pt | Portuguese | + | pt_BR | Portuguese (Brazil) | + | pt_PT | Portuguese (Portugal) | + | ro | Romanian | + | ro_RO | Romanian (Romania) | + | ru | Russian | + | ru_RU | Russian (Russia) | + | sk | Slovak | + | sk_SK | Slovak (Slovakia) | + | sl | Slovenian | + | sl_SI | Slovenian (Slovenia) | + | sq | Albanian | + | sq_AL | Albanian (Albania) | + | sr | Serbian | + | sr_BA | Serbian (Bosnia and Herzegovina) | + | sr_CS | Serbian (Serbia and Montenegro) | + | sr_ME | Serbian (Montenegro) | + | sr_RS | Serbian (Serbia) | + | sv | Swedish | + | sv_SE | Swedish (Sweden) | + | th | Thai | + | th_TH | Thai (Thailand) | + | th_TH_TH | Thai (Thailand,TH) | + | tr | Turkish | + | tr_TR | Turkish (Turkey) | + | uk | Ukrainian | + | uk_UA | Ukrainian (Ukraine) | + | vi | Vietnamese | + | vi_VN | Vietnamese (Vietnam) | + | zh | Chinese | + | zh_CN | Chinese (China) | + | zh_HK | Chinese (Hong Kong) | + | zh_SG | Chinese (Singapore) | + | zh_TW | Chinese (Taiwan) | + diff --git a/memory.md b/memory.md new file mode 100644 index 0000000..94ef869 --- /dev/null +++ b/memory.md @@ -0,0 +1,2 @@ +explain dynamic and static memory + diff --git a/one_click_deploy.md b/one_click_deploy.md new file mode 100644 index 0000000..090b82f --- /dev/null +++ b/one_click_deploy.md @@ -0,0 +1,22 @@ +## One Click Deploy + +### Sounds Good, What is it? + +This feature will pop up automatically once a platform is properly configured and a supported device is connected to the computer. +Since things can go wrong at many levels (platform may not be configured correctly, SDK may incorrectly installed, device may be improperly configured, kitty ate the USB cable, etc.), it's good to let the user know that it exists. + +Some platforms (at the time of this writing, only Android and Blackberry 10) can detect when a USB device is connected to the computer, and offer the user to automatically export, install and run the project (in debug mode) on the device. This feature is called, in industry buzz-words, "One Click Deploy" (though, it's technically two clicks...). + +### Steps for One Click Deploy + + 1. Configure target platform. + 2. Configure device (make sure it's in developer mode, likes the computer, usb is recognized, usb cable is plugged, etc). + 3. Connect the device.. + 4. And Voila! + +

+ +Click once.. and deploy! + + + diff --git a/paths.md b/paths.md new file mode 100644 index 0000000..1b04cac --- /dev/null +++ b/paths.md @@ -0,0 +1,25 @@ +# Path Separators + + +For the sake of supporting as many platforms as possible, Godot only accepts unix style path separators (/). These work everywhere, including Windows. +A path like: "C:\Projects" will become "c:/Projects". + +# Resource Path + +As mentioned before. Godot considers that a project exists at any given folder that contains an "engine.cfg" text file, even if such file is empty. +Accessing project files can be done by opening any path with "res://" as a base. For example, a texture located in the root of the project folder may be opened from the following path: "res://sometexture.png". + +# Userdata Path (Persistent Data) + +While the project is running, it is a very common scenario that the resource path will be read-only, due to it being inside a package, self contained executable, or system wide install location. +Storing persistent files in such scenarios should be done by using the "user://" prefix, for example: "user://gamesave.txt". + +In some devices (for example, mobile ad consoles) this path is unique for the app. Under desktop operating systems, the engine uses the typical ~/.Name (check the project name under the settings) in OSX and Linux, and APPDATA/Name for Windows. + + + + + + + + diff --git a/shader.md b/shader.md new file mode 100644 index 0000000..788da20 --- /dev/null +++ b/shader.md @@ -0,0 +1,227 @@ +# Shading Language + +### Introduction + +Godot uses a simplified shader language (almost a subset of GLSL). Shaders can be used for: + + +* Materials + +* Post-Process + +* 2D + +and are divided in *Vertex* and *Fragment* sections. + +### Language + +#### Typing + +The language is statically type and only supports a few operations. Arrays, classes, structures, etc are not supported. Several built-in datatypes are provided: + +#### Data Types + + | DataType | Description | + | -------- | ----------- | + | void | Void | + | bool | boolean (true or false) | + | float | floating point | + | vec2 | 2-component vector, float subindices (x,y or r,g ) | + | vec3 | 3-component vector, float subindices (x,y,z or r,g,b ) | + | vec4,color | 4-component vector, float subindices (x,y,z,w or r,g,b,a ) | + | mat3 | 3x3 matrix, vec3 subindices (x,y,z) | + | mat4 | 4x4 matrix, vec4 subindices (x,y,z,w) | + | texture | texture sampler, can only be used as uniform | + | cubemap | cubemap sampler, can only be used as uniform | + +#### Syntax + +The syntax is similar to C, with statements ending in ; , and comments as %%// and /* */%%. +Example: + + :::C + float a = 3; + vec3 b; + b.x = a; + ``` + + #### Swizzling + + It is possible to use swizzling to reasigning subindices or groups of subindices, in order: + + + vec3 a = vec3(1,2,3); + vec3 b = a.zyx; // b will contain vec3(3,2,1) + vec2 c = a.xy; // c will contain vec2(1,2) + vec4 d = a.xyzz; // d will contain vec4(1,2,3,3) + ``` + + #### Constructors + + Constructors take the regular amount of elements, but can also accept less if the element has more subindices, for example: + + + vec3 a = vec3( 1, vec2(2,3) ); + vec3 b = vec3( a ); + vec3 c = vec3( vec2(2,3), 1 ); + vec4 d = vec4( a, 5 ); + mat3 m = mat3( a,b,c ); + ``` + + + + ### Conditionals + + For now, only the "if" conditional is supported. Example: + + + if (a < b) { + c = b; + } + ``` + + ### Uniforms + + A variable can be declared as uniform. In this case, it's value will come from outside the shader (it will be the responsibility of the material or whatever using the shader to provide it). + + + uniform vec3 direction; + uniform color tint; + + vec3 result = tint.rgb * direction; + ``` + + + ### Functions + + Simple support for functions is provided. Functions can't access uniforms or other shader variables. + + + + vec3 addtwo( vec3 a, vec3 b) { + + return a+b; + } + + vec3 c = addtwo(vec3(1,1,1)+vec3(2,2,2)); + + ``` + + ### Built-In Functions + + Several Built-in functions are provided for convenience, listed as follows: + + ^ Function ^ Description ^ + | float **sin**( float ) | Sine | + | float **cos**( float ) | Cosine | + | float **tan**( float ) | Tangent | + | float **asin**( float ) | arc-Sine | + | float **acos**( float ) | arc-Cosine | + | float **atan**( float ) | arc-Tangent | + | vec_type **pow**( vec_type, float ) | Power | + | vec_type **pow**( vec_type, vec_type ) | Power (Vec. Exponent) | + | vec_type **exp**( vec_type ) | Base-e Exponential | + | vec_type **log**( vec_type ) | Natural Logarithm | + | vec_type **sqrt**( vec_type ) | Square Root | + | vec_type **abs**( vec_type ) | Absolute | + | vec_type **sign**( vec_type ) | Sign | + | vec_type **floor**( vec_type ) | Floor | + | vec_type **trunc**( vec_type ) | Trunc | + | vec_type **ceil**( vec_type ) | Ceiling | + | vec_type **fract**( vec_type ) | Fractional | + | vec_type **mod**( vec_type,vec_type ) | Remainder | + | vec_type **min**( vec_type,vec_type ) | Minimum | + | vec_type **min**( vec_type,vec_type ) | Maximum | + | vec_type **clamp**( vec_type value,vec_type min, vec_type max ) | Clamp to Min-Max | + | vec_type **mix**( vec_type a,vec_type b, float c ) | Linear Interpolate | + | vec_type **mix**( vec_type a,vec_type b, vec_type c ) | Linear Interpolate (Vector Coef.)| + | vec_type **step**( vec_type a,vec_type b) | %% a[i] < b[i] ? 0.0 : 1.0%%| + | float **length**( vec_type ) | Vector Length | + | float **distance**( vec_type, vec_type ) | Distance between vector. | + | float **dot**( vec_type, vec_type ) | Dot Product | + | vec3 **dot**( vec3, vec3 ) | Cross Product | + | vec_type **normalize**( vec_type ) | Normalize to unit length | + | vec3 **reflect**( vec3, vec3 ) | Reflect | + | color **tex**( texture, vec2 ) | Read from a texture in noormalized coords | + | color **texcube**( texture, vec3 ) | Read from a cubemap | + | color **texscreen**( texture, vec1 ) | Read from screen (generates a copy) | + + + ### Built-In Variables + + Depending on the shader type, several built-in variables are available, listed as follows: + + ##### Material - VertexShader== + + ^ Variable ^ Description ^ + | vec3 **VERTEX** | Pre-Transformed Vertex | + | vec3 **NORMAL** | Pre-Transformed Normal | + | vec3 **TANGENT** | Pre-Transformed Tangent | + | vec2 **UV** | UV | + | vec2 **UV2** | UV2 | + | color **COLOR** | Vertex Color | + | out vec4 **VAR1** | Varying 1 Output | + | out vec4 **VAR2** | Varying 2 Output | + | out float **SPEC_EXP** | Specular Exponent (for Vertex Lighting) | + | out float **POINT_SIZE** | Point Size (for points) | + | const mat4 **WORLD_MATRIX** | Object World Matrix | + | const mat4 **INV_CAMERA_MATRIX** | Inverse Camera Matrix | + | const mat4 **PROJECTION_MATRIX** | Projection Matrix | + | const float **INSTANCE_ID** | Instance ID (for multimesh)| + | const float **TIME** | Time (in seconds) | + + ##### Material - FragmentShader== + + ^ Variable ^ Description ^ + | const vec3 **VERTEX** | View-Space vertex | + | const vec4 **POSITION** | View-Space Position | + | const vec3 **NORMAL** | View-Space Normal | + | const vec3 **TANGENT** | View-Space Tangent | + | const vec3 **BINORMAL** | View-Space Binormal | + | const vec2 **UV** | UV | + | const vec2 **UV2** | UV2 | + | const color **COLOR** | Vertex Color | + | const vec4 **VAR1** | Varying 1 | + | const vec4 **VAR2** | Varying 2 | + | const vec2 **SCREEN_TEXEL_SIZE**| Size of Screen Pixel (for texscreen) | + | const float **TIME**| Time (in seconds) | + | out vec3 **DIFFUSE** | Diffuse Color | + | out vec4 **DIFFUSE_ALPHA** | Diffuse Color with Alpha | + | out vec3 **SPECULAR** | Specular Color | + | out vec3 **EMISSION** | Emission Color | + | out float **SPEC_EXP** | Specular Exponent (Fragment Version) | + | out float **GLOW** | Glow | + | out float **DISCARD** | Discard (any write > 0.5 discards the pixel) | + + ### Examples + + Material that reads a texture, a color and multiples them, fragment program: + + + + uniform color modulate; + uniform texture source; + + DIFFUSE = color.rgb * tex(source,UV).rgb; + + ``` + + Material that glows from red to white: + + + + DIFFUSE = vec3(1,0,0) + vec(1,1,1)*mod(TIME,1.0); + + ``` + + ### Notes + + + * **Do not** use DIFFUSE_ALPHA unless you really intend to use transparency. Transparent materials must be sorted by depth and slow down the rendering pipeline. For opaque materials, just use DIFFUSE. + * **Do not** use DISCARD unless you really need it. Discard makes rendering slower, specially on mobile devices. + * TIME may reset after a while (may last an hour or so), it's meant for effects that vary over time. + * In general, every built-in variable not used results in less shader code generated, so writing a single giant shader with a lot of code and optional scenarios is often not a good idea. + + --- //[[reduzio@gmail.com|Juan Linietsky]] 2013/11/10 18:10// + + \ No newline at end of file diff --git a/start.md b/start.md new file mode 100644 index 0000000..b4322ca --- /dev/null +++ b/start.md @@ -0,0 +1,167 @@ +**Note**: Please do not change the guest account password! + +# Introduction + +Welcome to the Godot Engine documentation center. The aim of these pages is to provide centralized access to all documentation-related materials. + +# Downloads + + + + +#### Executables: + + +* [Mac OSX 32 bits.](http://www.godotengine.org/builds/release/GodotOSX32.zip) + +* [Windows 32 bits.](http://www.godotengine.org/builds/release/godot_win32.exe) + +* [Windows 64 bits.](http://www.godotengine.org/builds/release/godot_win64.exe) + +* [Linux X11, 64 bits.](http://www.godotengine.org/builds/release/godot_x11.64) + +* [Linux Server (Headless), 64 bits.](http://www.godotengine.org/builds/release/godot_server.64) + +**NOTICE: iOS deployment targety will be available the coming weeks. ** + +**NOTICE: Godot requires at least OpenGL 2.1 support to run the editor, older Intel GPUs might not work. ** + +**NOTICE: if opening demos from the project manager does not work under Linux, decompress the binary with the command "upx -d godot_x11.64" ** + +#### Demos: + + +* [Demos & Examples.](http://www.godotengine.org/builds/demos/godot_demos.zip) + +#### Export Templates: + + +* [Export Templates](http://www.godotengine.org/builds/templates/export_templates.zip) Needed to Export to All Platforms. + + + +# Tutorials + +#### Basic (Step by Step) + + 1. [ Scenes and Nodes](tutorial_scene) + 2. [Scripting](tutorial_scripting) + 3. [Scripting (Continued)](tutorial_scripting_2) + 4. [Creating a 2D Game](tutorial_2d) + 5. [GUI Introduction](tutorial_gui) + 6. [Creating a Splash Screen](tutorial_splash) + 7. [Animation](tutorial_animation) + 8. [Resources](tutorial_resources) + 9. [File System](tutorial_fs) + 10. [SceneMainLoop](tutorial_scene_main_loop) + 11. [Singletons (Autoload)](tutorial_singletons) + +#### Intermediate + + +* [GUI Control Repositioning](tutorial_gui_repositioning) + +* [GUI Skinning](tutorial_gui_skinning) + +* [ Physics Engine (2D)](tutorial_physics_2d) + +* [Cut-Out Animation](tutorial_cutout) + +* [ Creating a 3D game](tutorial_3d) + +* [Using the AnimationTreePlayer](tutorial_animation_tree) + +* [Supporting Multiple Languages](tutorial_localization) + +* [Creating Resizable GUIs Efficiently](tutorial_resizable_gui) + +#### Advanced + + +* [ Servers (Low Levl API)](tutorial_servers) + + +* [Paths](paths) + +* [Thread Safety](thread_safety) Using Multiple Threads. + +* [Memory](memory) Memory model and administration. + + +#### Editor Plug-Ins + + +* [Editor Plugin](editor_plugin) Writing an editor extension. + +* [Editor Plugin](editor_res_node) Writing a Resource or Node editor extension. + +* [Editor Import-Export](editor_import) Writing an editor import-export extension. + +* [Editor Scene Loader](editor_scene_loader) Writing a scene format loader. + +* [Editor 3D Import](editor_import_3d) Writing a script for customizing imported 3D scenes. +# Reference + +#### Class List + + +* [Alphabetical Class List](class_list/class_list) List of classes in alphabetical order. + +* [Categorized Class List](class_list/category) List of classes organized by category. + +* [Inheritance Class Tree](class_list/inheritance) List of classes organized by inheritance. + +* [Relevant Classes](relevant_classes) List of the most relevant classes to learn first. + +#### Languages + + +* [GDScript](gdscript) Built-in, simple, flexible and efficient scripting language. + +* [Squirrel](squirrel) Optional, more complex scripting language. **[DEPRECATED]** + +* [Shader](shader) Built-in, portable, shader language. + +* [Locales](locales) List of supported locale strings. + +# Asset Pipeline + +#### Import + + +* [Import Process](import_process) The import process described. + +* [Importing Textures](import_textures) Importing textures. + +* [Importing 3D](import_3d) Importing 3D scenes. + +* [Importing Fonts](import_fonts) Importing fonts. + +* [Importing Audio Samples](import_samples) Importing audio samples. + +* [Importing Translations](import_translation) Importing translations. + +#### Export + + +* [Export](export) Exporting Projects. + +* [One Click Deploy](one_click_deploy) One Click Deploy. + +* [PC](export_pc) Exporting for PC (Mac, Windows, Linux). + +* [Android](export_android) Exporting for Android. + +* [BlackBerry 10](export_bb10) Exporting for BlackBerry 10. + +* [iOS](export_ios) Exporting for iOS. + +* [NaCL](export_nacl) Exporting for Google Native Client. + +* [HTML5](export_html5) Exporting for HTML5 (using asm.js). + +* [Consoles](export_consoles) Exporting for consoles (PS3, PSVita, etc). + +# Advanced + +[Advanced](advanced) Advanced Topics (C++ Programming, File Formats, Porting, etc). diff --git a/tutorial_2d.md b/tutorial_2d.md index ae30759..1dade08 100644 --- a/tutorial_2d.md +++ b/tutorial_2d.md @@ -5,21 +5,21 @@ In this simple tutorial, a basic game of Pong will be created. There are plenty ### Assets -Some assets are included for this tutorial, the {{::pong_assets.zip|pong pads, the ball and the divisor}}. +Some assets are included for this tutorial, the

+

Create a [Node2D](class_list/node2d) node for the project root. Node2D is the base type for the 2D engine. After this, add some sprites ([Sprite](class_list/sprite) node) and set each to the corresponding texture. The final scene layour should look similar to this (note: the ball is in the middle!): -```` +

The scene tree should, then look similar to this: -```` +

Save the scene as "pong.scn" and set it as the main scene in the project properties. @@ -32,7 +32,7 @@ Handling all possible input methods can be very frustrating and take a lot of co Open the project properties dialog again, but this time move to the "Input Map" tab. On it, add 4 actions: "left_move_up","left_move_down","right_move_up","right_move_down". Assign the keys that you desire. A/Z for left and Up/Down as keys should work in most cases. -```` +

### Script diff --git a/tutorial_animation.md b/tutorial_animation.md new file mode 100644 index 0000000..d8b169c --- /dev/null +++ b/tutorial_animation.md @@ -0,0 +1,69 @@ +# Animation Tutorial + +### Introduction + +This tutorial will explain how everything is animated in Godot. Godot animation system is extremely powerful and flexible. + +To begin, let's just use the scene from the previous tutorial (splash screen). The goal will be to add a simple animation to it. Here's a copy just in case:

+ +When a node of this type is selected, the animation editor panel will appear: + +

+ +So, it's time to create a new animation! Press the new animation button and name the animation "intro". + +

+ +After the animation has been created, then it's time to edit it, by pressing the "edit" button: + +

+ +### Editing the Animation + +Now this is when the magic happens! Several things happen when the "edit" button is pressed, the first one is that the animation editor appears above the animation panel. + +

+ +But the second, and most important, is that the property editor enters into "animation editing" mode. In this mode, a key icon appears next to every property of the property editor. This means that, in Godot, *any property of any object* can be animated: + +

+ + +### Making the Logo Appear + +Next, the logo will appear from the top of the screen. After selecting the animation player, the editor panel will stay visible until manually hidden (or the animation node is erased). Taking advantage of this, select the "logo" node and go to the "pos" property, move it up, to position: 114,-400. +Once in this position, press the key button next to the property: + +

+ +As the track is new, a dialog will appear asking to create it. Confirm it! + +

+ +Second, move the editor cursor to the end, by clicking here: + +

+ +Change the logo position to 114,0 and a keyframe again. With two keyframes, the animation happens. + +

+ +Pressing Play on the animation panel will make the logo descend. To test it by running the scene, the autoplay button can tag the animation to start automatically when the scene starts: + +

+ +And finally, when running the scene, the animation should look like this: + +

+ diff --git a/tutorial_fs.md b/tutorial_fs.md new file mode 100644 index 0000000..c85f6ee --- /dev/null +++ b/tutorial_fs.md @@ -0,0 +1,61 @@ +# File System + +### Introduction + +Filesystem usage is yet another hot topic in engine development. This means, where are assets stored, how are they accessed, how do multiple programmers edit the same repository, etc. + +Initial versions of the engine (and previous iterations before it was named Godot) used a database. Assets were stored there and assigned an ID. Other approaches were tested, too, with local databases, files with metadata, etc. To say truth, and after a long time, simplicity proved to be best and Godot stores all assets as files in the flesystem. + +### Implementation + +Godot stores resources to disk. Anything, from a script, to a scene or a PNG image is a resource to the engine. If a resource contains properties that referece other resources on disk, the path to that resource is included. If it has sub-resources that are built-in, the resource is saved in a single file together with all the bundled sub-resources. For example, a font resource is often saved with the character textures bundled inside. + +Metadata files were also dropped and the whole engine design tries to avoid them. The reason for this is simple, existing asset managers and VCSs are just much better than anything we can implement, so Godot tries the best to play along with SVN, Git, Mercurial, Perforce, etc. + +### engine.cfg + +The mere existence of this file marks that there is a Godot project in that directory and all sub-directories. +This file contains the project configuration in plain text, win.ini style, though it will work to mark the existence of a project even if the file is empty. + +Example of a filesystem: + +``` + +/engine.cfg +/enemy/enemy.scn +/enemy/enemy.gd +/enemy/enemysprite.png +/player/player.gd + +``` + +### Directory Delimiter + +Godot only supports "/" as a directory delimiter. This is done for portability reasons. All operating systems support this, even Windows, so a path such as c:\project\engine.cfg needs to be typed as c:/project/engine.cfg. + + +### Resource Path + +For accessing resources, using the host OS filesystem layout can be cumbersome and non portable. To solve this problem, the specal path %%"res://"%% was created. + +The path %%"res://"%% will always point at the project root (where engine.cfg is located, so in fact %%"res://engine.cfg"%% is always valid). + +This filesystem is read-write only when running the project locally from the editor. When exported or when running on different devices (such as phones or consoles, or running from DVD), the filesystem will become read-only and writing will no longer be permitted. + +### User Path + +Writing to disk is still needed often, from doing a savegame to downloading content packs. For this, the engine ensures that there is a special path %%"user://"%% that is always writable. + +### Host Filesystem + +Of course, opening the host filesystem always works, as this is always useful when Godot is used to write tools, but for shipped projects this is discouraged and may not even be supported in some platforms. + +### Drawbacks + + +Not everything is rosy. Using resources and files and the plain filesystem has two main drawbacks. The first is that moving assets around (renaming them or moving them from a directory to another inside the project) once they are referenced is not that easy. If this is done, then dependencies will need to be re-satisfied upon load. + +The second is that under Windows or OSX, file access is case insensitive. If a developer works in this operating system and saves a file like "myfile.PNG", then references it as "myfile.png", it will work there, but not on any other platform, such as Linux, Android, etc. It may also not work on exported binaries, which use a compressed package for files. + +Because of this, please instruct your team to use a specific naming convention for files when working with Godot! + diff --git a/tutorial_gui.md b/tutorial_gui.md new file mode 100644 index 0000000..bc1f538 --- /dev/null +++ b/tutorial_gui.md @@ -0,0 +1,107 @@ +# GUI Tutorial + +### Introduction + +If there is something that most programmers hate with passion, that is programming graphical user interfaces (GUIs). It's boring, tedious and unchallenging. Several aspects make matters worse such as: + + +* Pixel alignment of UI elements is difficult (so it looks just like the designer intends). + +* UIs are changed constantly due to design and usability issues that appear during testing. + +* Handling proper screen re-sizing for different display resolutions. + +* Animating several screen components, to make it look less static. + +GUI programming is one of the leading causes of programmer burnout. During the development of Godot (and previous engine iterations), several techniques and philosophies for UI development were put in practice, such as immediate mode, containers, anchors, scripting, etc. This was always done with the main goal of reducing the stress programmers had to face while putting together user interfaces. + +In the end, the resulting UI subsystem in Godot is an efficient solution to this problem, and works by mixing together a few different approaches. While the learning curve is a little steeper than in other toolkits, developers can put together complex user interfaces in very little time, by sharing the same set of tools with designers and animators. + +### Control + +The basic node for UI elements is [Control](class_list/control) (sometimes called "Widget" or "Box" in other toolkits). Every node that provides user interface functionality descends from it. + +When controls are put in a scene tree as a child of another control, it's coordinates (position, size) are always relative to the parent. This sets the basis for editing complex user interface quickly and visually. + +### Input and Drawing + +Controls receive input events by means of the [_input_event](class_list/control#_input_event)() callback. Only one control, the one in focus, will receive keyboard/joypad events (see [set_focus_mode](class_list/control#set_focus_mode)() and [grab_focus](class_list/control#grab_focus)(). + +Mouse Motion events are received by the control directly below the mouse pointer. When a control receives a mouse button pressed event, all subsequent motion events are received by the pressed control until that button is released, even if the pointer moves outside the control boundary. + +Like any class that inherits from [CanvasItem](class_list/canvasitem) (Control does), a [_draw](class_list/canvasitem#draw)() callback will be received at the begining and every time the control needs to be redrawn (programmer needs to call [update](class_list/canvasitem#update)() to enqueue the CanvasItem for redraw). If the control is not visible (yet aother CanvasItem property), the control does not receive any input. + +In general though, the programmer does not need to deal with drawing and input events directly when building UIs, (that is more useful when creating custom controls). Instead, controls emit different kinds of signals with contextural information for when action occurs. For example, a [Button](class_list/button) emits a "pressed" signal when pressed, a [Slider](class_list/slider) will emit a "value_changed" when dragged, etc. + +### Custom Control Mini Tutorial + +Before going into more depth, creating a custom control will be a good way to get the picture on how controls works, as they are not as complex as it might seem. +Additionally, even though Godot comes with dozens of controls for different purposes, it happens often that it's just easier to attain a specific functionality by creating a new one. + +To begin, create a single-node scene. The node is of type "Control" and has a certain area of the screen in the 2D editor, like this: + +

+ +Add a script to that node, with the following code: + +```python + +extends Control + +var tapped=false + +func _draw(): + + var r = Rect2( Vector2(), get_size() ) + if (tapped): + draw_rect(r, Color(1,0,0) ) + else: + draw_rect(r, Color(0,0,1) ) + +func _input_event(ev): + + if (ev.type==InputEvent.MOUSE_BUTTON and ev.pressed): + tapped=true + update() + +``` + +Then run the scene. When the rectangle is clicked/taped, it will go from blue to red. That synnergy between the events and drawing is pretty much how most controls work internally. + +

+

+ +### UI Complexity + +As mentioned before, Godot includes dozens of controls ready for using in a user interface. Such controls are divided in two categories. The first is a small set of controls that work well for creating most game user interfaces. The second (and most controls are of this type) are meant for complex user interfaces and uniform skinning trough styles. A description is presented as follows to help understand which one should be used in which case. + +#### Simplified UI Controls + +This set of controls is enough for most games, where complex interactions or ways to present information are not necessary. The can be skinned easily with regular textures. + + +* [Label](class_list/label) : Node used for showing text. + +* [TextureFrame](class_list/textureframe) : Displays a single texture, which can be scaled or kept fixed. + +* [TextureButton](class_list/texturebutton) : Displays a simple texture buttons, states such as pressed, hover, disabled, etc can be set. + +* [TextureProgress](class_list/textureprogress) : Displays a single textured progress bar. + + +Additionally, re-positioning of controls is most efficiently done with anchors in this case (see the [Size and Anchors](tutorial_gui_repositioning) tutorial for more info). + +In any case, it will happen often that even for simple games, more complex UI behaviors will be required. An example of this is a scrolling list of elements (for a high score table, for example), which needs a [ScrollContainer](class_list/scrollcontainer) and a [VBoxContainer](class_list/vboxcontainer). These kind of more advanced controls can be mixed with the regular ones seamlessly (they are all controls anyway). + +#### Complex UI Controls + +The rest of the controls (and there are dozens of them!) are meant for another set of scenarios, most commonly: + + +* Games that require complex UIs, such as PC RPGs, MMOs, strategy, sims, etc. + +* Creating custom development tools to speed up content creation. + +* Creating Godot Editor Plugins, to extend the engine functionality. + +Re-positioning controls for these kind of interfaces is more commonly done with containers (see the [Size and Anchors](tutorial_gui_repositioning) tutorial for more info). diff --git a/tutorial_gui_repositioning.md b/tutorial_gui_repositioning.md new file mode 100644 index 0000000..fb0c60f --- /dev/null +++ b/tutorial_gui_repositioning.md @@ -0,0 +1,42 @@ + +### Size and Anchors + +If a game was to be always run in the same device and at the same resolution, positioning controls would be a simple matter of setting the position and size of each one of them. Unfortunately, it is rarely the case. + +Only TVs nowadays have a standard resolution and aspect ratio. Everything else, from computer monitors to tablets, portable consoles and mobile phones have different resolutions and aspect ratios. + +There are several ways to handle this, but for now let's just imagine that the screen resolution has chanced and the controls need to be re-positioned. Some will need to follow the bottom of the screen, others the top of the screen, or maybe the right or left margins. + +

+ +This is done by editing the *margin* properties of controls. Each control has four margins: left, right, bottom and top. By default all of them represent a distance in pixels relative to the top-left corner of the parent control or (in case there is no parent control) the viewport. + +

+ +When horizontal (left,right) and/or vertical (top,bottom) anchors are changed to END, the margin values become relative to the bottom-right corner of the parent control or viewport. + +

+ +Here the control is set to expand it's bottom-right corner with that of the parent, so when re-sizing the parent, the control will always cover it, leaving a 20 pixel margin: + +

+ +Finally, there is also a ratio option, where 0 means left, 1 means right and anything in between is interpolated. + +### Containers + + +This poses a difficult problem + +There are two ways of dealing + + +style boxes + +title menu example + +containers + +theme + +focus diff --git a/tutorial_resources.md b/tutorial_resources.md new file mode 100644 index 0000000..bc7306b --- /dev/null +++ b/tutorial_resources.md @@ -0,0 +1,83 @@ +# Resources + +### Nodes AND Resources + +So far, [Node](class_list/node) have been the most important datatype in Godot, as most of the behaviors and features of the engine are implemented through them. There is, though, another datatype that is equally as important. That is [Resource](class_list/resource).. + +Where *Nodes* focus on behaviors, such as drawing a sprite, drawing a 3D model, physics, GUI controls, etc, +*Resources* are mere *data containers*. This means that they don't do any action nor process any information. Resources just contain data. + +Examples of resources are [Texture](class_list/texture), [Script](class_list/script), [Mesh](class_list/mesh), [Animation](class_list/animation), [Sample](class_list/sample), [AudioStream](class_list/audiostream), [Font](class_list/font), [Translation](class_list/translation), etc. + +When Godot saves o loads (from disk) a scene (.scn or .xml), an image (png, jpg), a scrit (.gd) or pretty much anything, that file is considered a resource. + +When a resource is loaded from disk, **it is always loaded once**. That means, if there is a copy of that resource already loaded in memory, trying to load the resource again will just return the same copy again and again. This corresponds with the fact that resources are just data containers, so there is no need to have them duplicated. + +Typically, every object in Godot (Node, Resource, or anything else) can export properties, properties can be of many types (like a string, integer, Vector2, etc) and one of those types can be a resource. This means that both nodes and resources can contain resources as properties. To make it a litle more visual: + +

+ +### External vs Built-In + +The resource properties can reference resources in two ways, *external* (on disk) or *built-in*. +To be more specific, here's a [Texture](class_list/texture) in a [Sprite](class_list/sprite) node: + +

+ +Pressing the the ">" button the right side of the preview, allows to view and edit the resources properties. One of the properties (path) shows where did it come from. In this case, it came from a png image. + +

+ +When the resource comes from a file, it is considered an *external* resource. If the path property is erased (or never had a path o begin with), it is then considered a built-in resource. + +For example, if the path %%"res://robi.png"%% is erased from the "path" property in the above example, and then the scene is saved, the resource will be saved inside the .scn scene file, no longer referencing the external "robi.png". However, even if saved as built-in, and even though the scene can be instanced multiple times, the resource will still always be loaded once. That means, different Robi robot scenes instanced at the same time will still share the same image. + +### Loading Resources from Code + + +Loading resources from code is easy, there are two ways to do it. The first is to use load(), like this: + +```python + +func _ready(): + + var res = load("res://robi.png") # resource is loaded when line is executed + get_node("sprite").set_texture(res) +``` + +The second way is more optimal, but only works with a string constant parameter, because it loads the resource at compile-time. + +```python + +func _ready(): + + var res = preload("res://robi.png") # resource is loaded at compile time + get_node("sprite").set_texture(res) +``` + +### Loading Scenes + +Scenes are also resources, but there is a catch. Scenes saved to disk are resources of type [PackedScene](class_list/packedscene), this means that the scene is packed inside a resource. + +To obtain an instance of the scene, the method [instance](class_list/packedscene#instance)() must be used. +```python +func _on_shoot(): + + var bullet = preload("res://bullet.scn").instance() + add_child(bullet) +``` + +This method creates the nodes in hierarchy, configures them (sets all the properties) and returns the root node of the scene, which can be added to any other node. +The approach has several advantages. As the [instance](class_list/packedscene#instance)() function is pretty fast, adding extra content to the scene can be done efficiently. New enemies, bullets, effects, etc can be added or removed quickly, without having to load them again from disk each time. It is important to remember that, as always, images, meshes, etc are all shared between the scene instances. + +### Freeing Resources + +Resource extends from [Reference](class_list/reference). As such, when a resource is no longer in use, it will automatically free itelf. Since, in most cases, Resources are contained in Nodes, scripts or other resources, when a node is removed or freed, all the children resources are freed too. + +### Scripting + +Like any object in Godot, not just nodes, Resources can be scripted too. However, there isn't generally much of a win, as resources are just data containers. + + + + diff --git a/tutorial_scene.md b/tutorial_scene.md index 179cb0e..7e12454 100644 --- a/tutorial_scene.md +++ b/tutorial_scene.md @@ -2,7 +2,7 @@ ### Introduction -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=chef.png) +

Imagine for a second that you are not a game developer anymore. Instead, You are a chef! Change your hipster outfit for a toque and a double breasted jacket. Now, instead of making games, you create new and delicious recipes for your guests. @@ -28,8 +28,7 @@ But let's go to the basics. A node is a basic element for creating a game, it ha * Can be added other nodes as children. -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=tree.png) - +

The last one is very important. Nodes can have other nodes as children. When arranged in this way, the nodes become a *tree*. In Godot, the ability to arrange nodes in this way creates a powerful tool for organizing the projects. Since different nodes have different functions, combining them allows to create more complex functions. @@ -38,7 +37,7 @@ This is probably not clear yet and it makes little sense, but everything will cl ### Scenes -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=scene.png) +

Now that the existence of nodes has been defined, the next logical step is to explain what a Scene is. A scene is composed of a group of nodes organized hierarchically (in tree fashion). It has the following properties: @@ -61,58 +60,60 @@ Theory is boring, so let's change subject and go practical. Following a long tra When godot executable is run outside a project, the Project Manager appears. This helps developers manage their projects. -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=newproject.png) +

To create a new project, the "New Project" option must be used. Choose and create a path for the project and specify the project name: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=newproj.png) +

### Editor Once the "New Project" is created, the next step is opening it. This will open the Godot editor. Here is how the editor looks when freshly opened: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=editor.png) +

+ As mentioned before, making games in Godot feels like being in a kitchen, so let's open the refrigerator and add some fresh nodes to the project. We'll begin with a Hello World! To do this, the "New Node" button must be pressed: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=newnode.png) +

+ This will open the Create Node dialog, showing the long list of nodes that can be created: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=createnode.png) +

From there, select the "Label" node first. Searching for it is probably the quickest way: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=nodesearch.png) +

And finally, create the Label! A lot happens when Create is pressed: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=addedlabel.png) +

First of all, the scene is changed to the 2D editor (because Label is a 2D Node type), and the Label appears, selected, at the top left corner of the viewport. The node appears in the scene tree editor (box in the top right corner), and the label properties apear in the Inspector (box in the bottom right corner). The next step, will be to change the "Text" Property of the label, let change it to "Hello, World!": -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=hw.png) +

Ok, everything's ready to run the scene! Press the PLAY SCENE Button on the top bar (or hit F6): -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=playscene.png) +

Aaaand.. Oops. -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=neversaved.png) +

Scenes need to be saved to be run, so save the scene to something like hello.scn in Scene -> Save: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=savescene.png) +

And here's when something funny happens. The file dialog is a special file dialog, and only allows to save inside the project. %%The project root is "res://" which means "resource path. This means that files can only be saved inside the project. For the future, when doing file operations in Godot, remember that "res://" is the resource path, and no matter the platform or install location, it is the way to locate where resource files are from inside the game.%% After saving the scene and pressing run scene again, the "Hello, World!" demo should finally execute: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=helloworld.png) +

Success!! @@ -126,7 +127,7 @@ To access that dialog, simply go to Scene -> Project Settings. Once the window opens, the task will be to select a main scene. This can be done easily by changing the application/main_scene property and selecting 'hello.scn'. -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=main_scene.png) +

With this change, pressing the regular Play button (or F5) will run the project, no matter which scene is being edited. diff --git a/tutorial_scene_main_loop.md b/tutorial_scene_main_loop.md new file mode 100644 index 0000000..78f7e63 --- /dev/null +++ b/tutorial_scene_main_loop.md @@ -0,0 +1,74 @@ +# SceneMainLoop + +### Introduction + +This is where things start getting abstract, but don't panic, as there's not really more depth than this. +In previous tutorials, everything revolves around the concept of Nodes, scenes are made of them, and they become active once they enter the active scene. + +This deserves going a little more into depth. In fact, the scene system is not even a core component of Godot, as it is possible to skip it and make a script (or C++ code) that talks directly to the [Servers](tutorial_servers). But making a game that way would be a lot of work and is reserved for other uses. + +### MainLoop + +The way Godot works internally is as follows. There is the the [OS](class_list/os) class, which is the only instance that runs at the beginning. Afterwards, all drivers, servers, scripting languages, scene system, etc are loaded. +When initialization is complete, [OS](class_list/os) needs to be supplied a [MainLoop](class_list/mainloop) to run. Up to this point, all this is internals working (you can check main/main.cpp file in the source code if you are ever interested to see how this works internally). + +The user program, or game, starts in the MainLoop. This class has a few methods, for initialization, idle (frame-syncronized callback), fixed (physics-synchronized callback), and input. Again, this is really low level and when making games in Godot, writing your own MainLoop does not even make sense. + +### SceneMainLoop + +One of the ways to explain how Godot works, is that it's a high level game engine over a low level middleware. +The scene system is the game engine, while the [OS](class_list/os) and servers are the low level API. + +In any case, the scene system provides it's own main loop to OS, [SceneMainLoop](class_list/scenemainloop). +This is automatically instanced and set when running a scene, no need to do any extra work. + +It's important to know that this class exists because it has a few important uses: + + +* It contains the root [Viewport](class_list/viewport), when a scene is first opened, it's added as a child of it to become part of the active scene (more on that next) + +* It contains information about the groups, and has means to call all nodes in a group, or get a list of them. + +* It contains some global state functionality, such as setting pause mode, or quitting the process. + +When a node is part of the active scene, the [SceneMainLoop](class_list/scenemainloop) can be obtained by simply calling [Node.get_scene](class_list/node#get_scene)(). + +### Root Viewport + +The root [Viewport](class_list/viewport) is always a top of the scene. From a node, it can be obtained in two different ways: + +```python + get_scene().get_root() # access via scenemainloop + get_node("/root") # access via absolute path +``` + +This node contains the main viewport, anything that is a child of a [Viewport](class_list/viewport) is drawn inside of it by default, so it makes sense that the top of all nodes is always a node of this type, otherwise nothing would be seen! + +While other viewports can be created in the scene (for split-screen effects and such), this one is the only one that is never created by the user. It's created automatically inside SceneMainLoop. + +### Active Scene + +When a node is connected, directly or indirectly, to the root viewport, it becomes part of the active scene. +This means that, as explained in previous tutorials, will get the _enter_scene() and _ready() callbacks (as well as _exit_scene()). + +

+ +When nodes become active (inside the scene), they get access to everything they need to process, get input, display 2D and 3D, notifications, play sound, groups, etc. When they are removed from the active scene, they lose it. + +### Tree Order + +Most node operations in Godot, such as drawing 2D, processing or getting notifications are done in tree order. This means that parents and siblings with less order will get notified before the current node. + +

+ +### "Becoming Active" In Detail + + 1. A scene is loaded from disk or created by scripting. + 2. The root node of that scene (only one root, remember?) is added as either a child of the “root” Viewport (from SceneMainLoop), or to any child or grand-child of it. + 3. Every node of the newly added scene, will receive the “enter_scene” notification ( _enter_scene() callback in GDScript) in top-to-bottom order. + 4. An extra notification, “ready” ( _ready() callback in GDScript) is provided for convenience, when a node and all it’s children are inside the active scene. + 5. When a scene (or part of it) is removed, they receive the “exit scene” rotification ( _exit_scene() callback in GDScript) in bottom-to-top order + + + + diff --git a/tutorial_scripting.md b/tutorial_scripting.md index f7be07f..1adff86 100644 --- a/tutorial_scripting.md +++ b/tutorial_scripting.md @@ -18,8 +18,10 @@ Godot also uses the [extend](http://c2.com/cgi/wiki?EmbedVsExtend) pattern for s [GDScript](gdscript) (click link for reference) is a dynamically typed scripting language to fit inside Godot. It was designed with the following goals: -* First and most importantly, making it simple, familiar and as easy to learn as possible. -* Making the code readable and error safe. The syntax is mostly borrowed from Python. + +* First and most importantly, making it simple, familiar and as easy to learn as possible. + +* Making the code readable and error safe. The syntax is mostly borrowed from Python. Programmers generally take a few days to learn it, and within two weeks feel comfortable with it. @@ -35,17 +37,18 @@ Before continuing, please make sure to read the [GDScript](gdscript) reference. This tutorial will begin by scripting a simple GUI scene. Use the add node dialog to create the following hierarchy, with the following nodes: -* Panel + +* Panel * Label * Button It should look like this in the scene tree: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=scriptscene.png) +

And try to make it look like this in the 2D editor, so it makes sense: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=scriptsceneimg.png) +

Finally, save the scene, a fitting name could be "sayhello.scn" @@ -53,22 +56,23 @@ Finally, save the scene, a fitting name could be "sayhello.scn" Select the Panel node, then press the "Add Script" Icon as follows: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=addscript.png) +

The script creation diallog will popup. This dialog allows to select the language, class name, etc. GDScript does not use class names in script files, so that field is not editable. The script should inherit from "Panel" (as it is meant to extend the node, which is of Panel type, this is automatically filled anyway). Select the filename for the script (if you saved the scene previously, one will be automatically generated as sayhello.gd) and push "Create": -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=scriptcreate.png) +

Once this is done, the script will be created and added to the node. You can see this both as an extra icon in the node, as well as in the script property: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=scriptadded.png) +

+ To edit the script, pushing the icon above should do it (although, the UI will take you directly to the Script editor screen). So, here's the template script: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=script_template.png) +

There is not much in there. The "_ready()" function is called when the node (and all it's children) entered the active scene. (Remember, It's not a constructor, the constructor is "_init()" ). @@ -78,10 +82,11 @@ Signals are used mostly in GUI nodes, (although other nodes have them too). Sign There is a GUI for connecting signals, just select the node and press the "Signals" button: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=signals.png) +

+ Which will show the list of signals a Button can emit. -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=button_connections.png) +

But this example will not use it. We don't want to make things *too* easy. So please close that screen! In any case, at this point it is clear that that we are interested in the "pressed" signal, so instead of doing it with the visual interface, the connection will be done using code. @@ -91,26 +96,33 @@ For this, there is a function that is probably the one that Godot programmers wi To fetch the button, the following must be used: ```python + get_node("Button") + ``` So, next, a callback will be added for when a button is pressed, that will change the label's text: ```python -func _on_button_pressed(): - get_node("Label").set_text("HELLO!") + +func _on_button_pressed(): + get_node("Label").set_text("HELLO!") + ``` Finally, the button "pressed" signal will be connected to that callback in _ready(), by using [connect](class_list/object#connect)(). ```python + func _ready(): - get_node("Button").connect("pressed",self,"_on_button_pressed") + get_node("Button").connect("pressed",self,"_on_button_pressed") ``` The final script should look like this: ```python + + extends Panel # member variables here, example: @@ -119,15 +131,22 @@ extends Panel # var b="textvar" func _on_button_pressed(): - get_node("Label").set_text("HELLO!") + get_node("Label").set_text("HELLO!") func _ready(): - get_node("Button").connect("pressed",self,"_on_button_pressed") + get_node("Button").connect("pressed",self,"_on_button_pressed") + + ``` Running the scene should have the expected result when pressing the button: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=scripthello.png) +

+ + + + + diff --git a/tutorial_scripting_2.md b/tutorial_scripting_2.md index f0dc435..3d69cc1 100644 --- a/tutorial_scripting_2.md +++ b/tutorial_scripting_2.md @@ -9,13 +9,14 @@ However,it is still a very common case to have a script process on every frame. Idle processing is activated with the [Node.set_process](class_list/node#set_process)() function. Once active, the [Node._process](class_list/node#set_process)() callback will be called every frame. Example: ```python + func _ready(): - set_process(true) + set_process(true) func _process(delta): - [dosomething..] -``` + [dosomething..] +``` The delta parameter describes the time elapsed (in seconds, as floating point) since the previous call to _process(). Fixed processing is similar, but only needed for synchronization with the physics engine. @@ -27,11 +28,12 @@ extends Label var accum=0 func _ready(): - set_process(true) + set_process(true) func _process(delta): - accum+=delta - set_text(str(accum)) + accum+=delta + set_text(str(accum)) + ``` Which will show a counter increasing each second. @@ -40,28 +42,34 @@ Which will show a counter increasing each second. Nodes can be added to groups (as many as desired per node). This is a simple yet useful feature for organizing large scenes. There are two ways to do this, the first is from the UI, from tne Groups button: -![](http://www.godotengine.org/wiki/lib/exe/fetch.php?media=groups.png) +

And the second from code. One useful example would be, for example, to tag scenes which are enemies. ```python + func _ready(): - add_to_group("enemies") + add_to_group("enemies") + ``` This way, if the player, sneaking into the secret base, is discovered, all enemies can be notified about the alarm sounding, by using [SceneMainLoop.call_group](class_list/scenemainloop#call_group)(): ```python + func _on_discovered(): - get_scene().call_group(0,"guards","player_was_discovered") + get_scene().call_group(0,"guards","player_was_discovered") + ``` The above code calls the function "player_was_discovered" on every member of the group "guards". Optionally, it is possible to get the full list of "guards" nodes by calling [SceneMainLoop.get_nodes_in_group](class_list/scenemainloop#get_nodes_in_group)(): ```python + var guards = get_scene().get_nodes_in_group("guards") + ``` More will be added about [SceneMainLoop](class_list/scenemainloop) later. @@ -72,12 +80,14 @@ More will be added about [SceneMainLoop](class_list/scenemainloop) later. Godot has a system of notifications. This is usually not needed to be used from scripting, as it's too low level and virtual functions are provided for most of them. It's just good to know they exists. Simply add a [Object._notification](class_list/object#_notification)() function in your script: ```python + func _notification(what): if (what==NOTIFICATION_READY): print("This is the same as overriding _ready()...") elif (what==NOTIFICATION_PROCESS): var delta = get_process_time() print("This is the same as overriding _process()...") + ``` The documentation of each class in the [class list](class_list/class_list) shows the notifications it can receive. However, again, for most cases script provides simpler overrideable functions. @@ -87,6 +97,7 @@ The documentation of each class in the [class list](class_list/class_list) shows As mentioned before, it's better to use these functions. Nodes provide many useful overrideable functions, which are described as follows: ```python + func _enter_scene(): pass # When the node enters the active scene, this function is called. Children nodes have not entered the active scene yet. In general, it's better to use _ready() for most cases. @@ -107,4 +118,7 @@ func _paused(): func _unpaused(): pass #Called when game is unpaused + ``` + + diff --git a/tutorial_singletons.md b/tutorial_singletons.md new file mode 100644 index 0000000..dcd32d5 --- /dev/null +++ b/tutorial_singletons.md @@ -0,0 +1,126 @@ +# Singletons (AutoLoad) + +### Introduction + +Scene Singletons are very useful things, as they represent a very common use case, but it's not clear at the begining where their value is. + +The scene system is very useful, but by itself it has a few drawbacks: + + +* There is no "common" place to store information (such as core, items obtained, etc) between two scenes. + +* It is possible to make a scene that loads other scenes as children and frees them, while keeping that information, but then if that is done, it's not possible to run a scene alone by itself and expect it to work + +* It is also possible to store persistent information to disk in %%user://%% and have scenes always load it, but saving/loading that while changing scenes is cumbersome. + +So, after using Godot for a while, it becomes clear that it is necessary to have parts of a scene that: + + +* Are always loaded, no matter which scene is opened from the editor. + +* Can keep global variables, such as player information, items, money, etc. + +* Can handle switching of scenes and transitions. + +* Just have something that acts like a singleton, since GDScript does not support global variables by design. + +For this, the option for auto-loading nodes and scripts exists. + +### Autoload + +Autoload can be a scene, or a script that inherits from Node (a Node will be created and the script will be set to it). They are added to the project in the Scene -> Project Settings -> AutoLoad tab. + +Each autoload needs a name, this name will be the node name, and the node will be always added to the root viewport before any scene is loaded. + +

+ +This means, that a for a singleton named "playervariables", any node can access it by requesting: + +```python + +var player_vars = get_node("/root/playervariables") + +``` + +### Scene Switcher + +This short tutorial will explain how to make a scene switcher by using autoload. +First download the template from here:

+ +Save the script to a file global.gd: + +

+ + +The script should be opened in the script editor. Next step will be adding it to autoload, for this, go to: Scene -> Project Settings -> AutoLoad and add a new autoload with name "global" that points to this file: + +

+ +Now, when any scene is run, the script will be always loaded. +So, going back to it, In the _ready() function, the current scene will be fetched. Both the current scene and global.gd are children of root, but the autoloaded nodes are always first. This means that the last child of root is always the loaded scene. + +Also, make sure that global.gd extends from Node, otherwise it won't be loaded. + +```python + +extends Node + +var current_scene = null + +func _ready(): + var root = get_scene().get_root() + current_scene = root.get_child( root.get_child_count() -1 ) + +``` + +Next, is the function for changing scene. This function will erase the current scene and replace it by the requested one: + +```python + +func goto_scene(scene): + var s = ResourceLoader.load(scene) + current_scene.queue_free() + current_scene = s.instance() + get_scene().get_root().add_child(current_scene) + +``` + +Finally, all that is left is to fill the empty functions in scene_a.gd and scene_b.gd: + +```python +#add to scene_a.gd + +func _on_goto_scene_pressed(): + get_node("/root/global").goto_scene("res://scene_b.scn") + +``` + +and + +```python +#add to scene_b.gd + +func _on_goto_scene_pressed(): + get_node("/root/global").goto_scene("res://scene_a.scn") + +``` + +Finally, by running the project it's possible to switch bewtween both scenes y pressing the button! + + + + + + + + + + diff --git a/tutorial_splash.md b/tutorial_splash.md new file mode 100644 index 0000000..465e332 --- /dev/null +++ b/tutorial_splash.md @@ -0,0 +1,33 @@ +# Splash Screen + +### Tutorial + +This will be a simple tutorial to cement the basic idea of how the GUI subsystem works. The goal will be to create a really simple, static, splash screen. + +Following is a file with the assets that will be used: + +

+

+ +The nodes 'background" and "logo" are of [TextureFrame](class_list/textureframe) type. These have a special property for setting the texture to be displayed, just load the corresponding file. + +

+ +The node "start" is a [TextureButton](class_list/texturebutton), it takes several images for different states, but only the normal and pressed will be supplied in this example: + +

+ +Finally, the node "copyright" is a [Label](class_list/label). Labels can be set a custom font by editing the following property: + +

+ +As a side note, the font was imported from a TTF, there is a [specific tutorial](import_fonts) for importing fonts. + +