godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-07 02:12:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

Revamping of the docs organisation for a more coherent TOC

Browse Source 
Only the pages were moved so far and some empty ones created,
the up-to-date toctrees come in the next commit.

(cherry picked from commit b408bdb918)
This commit is contained in:
Julian Murgia
2017-03-29 13:59:20 +02:00
committed by Rémi Verschelde
parent 6a730cb057
commit 5e05011eae
148 changed files with 0 additions and 376 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
development/compiling/batch_building_templates.rst Normal file
View File

@@ -0,0 +1,175 @@
.. _doc_batch_building_templates:
Batch building templates
========================
.. note:: This page is outdated and needs to be updated or removed.
The following is almost the same script that we use to build all the
export templates that go to the website. If you want to build or roll them
yourself, this might be of use.
(note: Apple stuff is missing)
::
#This script is intended to run on Linux or OSX. Cygwin might work.
# if this flag is set, build is tagged as release in the version
# echo $IS_RELEASE_BUILD
#Need to set path to EMScripten
export EMSCRIPTEN_ROOT=/home/to/emscripten
#Build templates
#remove this stuff, will be created anew
rm -rf templates
mkdir -p templates
# Windows 32 Release and Debug
scons -j 4 p=windows target=release tools=no bits=32
cp bin/godot.windows.opt.32.exe templates/windows_32_release.exe
upx templates/windows_32_release.exe
scons -j 4 p=windows target=release_debug tools=no bits=32
cp bin/godot.windows.opt.debug.32.exe templates/windows_32_debug.exe
upx templates/windows_32_debug.exe
# Windows 64 Release and Debug (UPX does not support it yet)
scons -j 4 p=windows target=release tools=no bits=64
cp bin/godot.windows.opt.64.exe templates/windows_64_release.exe
x86_64-w64-mingw32-strip templates/windows_64_release.exe
scons -j 4 p=windows target=release_debug tools=no bits=64
cp bin/godot.windows.opt.debug.64.exe templates/windows_64_debug.exe
x86_64-w64-mingw32-strip templates/windows_64_debug.exe
# Linux 64 Release and Debug
scons -j 4 p=x11 target=release tools=no bits=64
cp bin/godot.x11.opt.64 templates/linux_x11_64_release
upx templates/linux_x11_64_release
scons -j 4 p=x11 target=release_debug tools=no bits=64
cp bin/godot.x11.opt.debug.64 templates/linux_x11_64_debug
upx templates/linux_x11_64_debug
# Linux 32 Release and Debug
scons -j 4 p=x11 target=release tools=no bits=32
cp bin/godot.x11.opt.32 templates/linux_x11_32_release
upx templates/linux_x11_32_release
scons -j 4 p=x11 target=release_debug tools=no bits=32
cp bin/godot.x11.opt.debug.32 templates/linux_x11_32_debug
upx templates/linux_x11_32_debug
# Server for 32 and 64 bits (always in debug)
scons -j 4 p=server target=release_debug tools=no bits=64
cp bin/godot_server.server.opt.debug.64 templates/linux_server_64
upx templates/linux_server_64
scons -j 4 p=server target=release_debug tools=no bits=32
cp bin/godot_server.server.opt.debug.32 templates/linux_server_32
upx templates/linux_server_32
# Android
**IMPORTANT REPLACE THIS BY ACTUAL VALUES**
export ANDROID_HOME=/home/to/android-sdk
export ANDROID_NDK_ROOT=/home/to/android-ndk
# git does not allow empty dirs, so create those
mkdir -p platform/android/java/libs/armeabi
mkdir -p platform/android/java/libs/x86
#Android Release
scons -j 4 p=android target=release
cp bin/libgodot.android.opt.so platform/android/java/libs/armeabi/libgodot_android.so
./gradlew build
cp platform/android/java/build/outputs/apk/java-release-unsigned.apk templates/android_release.apk
#Android Debug
scons -j 4 p=android target=release_debug
cp bin/libgodot.android.opt.debug.so platform/android/java/libs/armeabi/libgodot_android.so
./gradlew build
cp platform/android/java/build/outputs/apk/java-release-unsigned.apk templates/android_debug.apk
# EMScripten
scons -j 4 p=javascript target=release
cp bin/godot.javascript.opt.html godot.html
cp bin/godot.javascript.opt.js godot.js
cp tools/html_fs/filesystem.js .
zip javascript_release.zip godot.html godot.js filesystem.js
mv javascript_release.zip templates/
scons -j 4 p=javascript target=release_debug
cp bin/godot.javascript.opt.debug.html godot.html
cp bin/godot.javascript.opt.debug.js godot.js
cp tools/html_fs/filesystem.js .
zip javascript_debug.zip godot.html godot.js filesystem.js
mv javascript_debug.zip templates/
# BlackBerry 10 (currently disabled)
#./path/to/bbndk/bbndk-env.sh
#scons -j 4 platform/bb10/godot_bb10_opt.qnx.armle target=release
#cp platform/bb10/godot_bb10_opt.qnx.armle platform/bb10/bar
#scons -j 4 platform/bb10/godot_bb10.qnx.armle target=release_debug
#cp platform/bb10/godot_bb10.qnx.armle platform/bb10/bar
#cd platform/bb10/bar
#zip -r bb10.zip *
#mv bb10.zip ../../../templates
#cd ../../..
# BUILD ON MAC
[...]
# Build release executables with editor
mkdir -p release
scons -j 4 p=server target=release_debug bits=64
cp bin/godot_server.server.opt.tools.64 release/linux_server.64
upx release/linux_server.64
scons -j 4 p=x11 target=release_debug tools=yes bits=64
cp bin/godot.x11.opt.tools.64 release/godot_x11.64
# upx release/godot_x11.64 -- fails on some linux distros
scons -j 4 p=x11 target=release_debug tools=yes bits=32
cp bin/godot.x11.opt.tools.32 release/godot_x11.32
scons -j 4 p=windows target=release_debug tools=yes bits=64
cp bin/godot.windows.opt.tools.64.exe release/godot_win64.exe
x86_64-w64-mingw32-strip release/godot_win64.exe
#upx release/godot_win64.exe
scons -j 4 p=windows target=release_debug tools=yes bits=32
cp bin/godot.windows.opt.tools.32.exe release/godot_win32.exe
x86_64-w64-mingw32-strip release/godot_win32.exe
#upx release/godot_win64.exe
[..] # mac stuff
# Update classes.xml (used to generate doc)
cp doc/base/classes.xml .
release/linux_server.64 -doctool classes.xml
cd demos
rm -f godot_demos.zip
zip -r godot_demos *
cd ..
cd tools/export/blender25
zip -r bettercollada *
mv bettercollada.zip ../../..
cd ../../..

256
development/compiling/compiling_for_android.rst Normal file
View File

@@ -0,0 +1,256 @@
.. _doc_compiling_for_android:
Compiling for Android
=====================
.. highlight:: shell
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.
Also, you still need to do all the steps mentioned in the
:ref:`doc_exporting_for_android` tutorial before attempting your custom
export template.
Requirements
------------
For compiling under Windows, Linux or OSX, the following is required:
- Python 2.7+ (3.0 is untested as of now)
- SCons build system
- [Windows only] PyWin32 (optional, for parallel compilation)
- Android SDK version 23.0.3 [Note: Please install all Tools and Extras of sdk manager]
- Android build tools version 19.1
- Android NDK r13 or later
- Gradle (will be downloaded and installed automatically if missing)
- JDK 6 or later (either OpenJDK or Oracle JDK) - JDK 9 is untested as of now
Setting up the buildsystem
--------------------------
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.
To set those environment variables on Windows, press Windows+R, type
"control system", then click on **Advanced system settings** in the left
pane, then click on **Environment variables** on the window that
appears.
To set those environment variables on Unix (e.g. Linux, Mac OSX), use
``export ANDROID_HOME=/path/to/android-sdk`` and
``export ANDROID_NDK_ROOT=/path/to/android-ndk``.
Where /path/to/android-sdk and /path/to/android-ndk is the path where Android Sdk
and Android Ndk are placed on you PC.
Toolchain
~~~~~~~~~
We usually try to keep the Godot Android build code up to date, but
Google changes their toolchain versions very often, so if compilation
fails due to wrong toolchain version, go to your NDK directory and check
the current number, then set the following environment variable:
::
NDK_TARGET (by default set to "arm-linux-androideabi-4.9")
Building the export templates
-----------------------------
Godot needs two export templates for Android: the optimized "release"
template (`android_release.apk`) and the debug version (`android_debug.apk`).
Compiling the standard export templates is done by calling scons with
the following arguments:
- Release template (used when exporting with "Debugging Enabled" OFF)
::
C:\godot> scons platform=android target=release
C:\godot> cd platform/android/java
C:\godot\platform\android\java> gradlew build
(on Linux/OSX, execute the `gradlew` script with `./gradlew build`)
The resulting APK is in:
::
bin\android_release.apk
- Debug template (used when exporting with "Debugging Enabled" ON)
::
C:\godot> scons platform=android target=release_debug
C:\godot> cd platform/android/java
C:\godot\platform\android\java> gradlew build
The resulting APK is in:
::
bin\android_debug.apk
Faster compilation
~~~~~~~~~~~~~~~~~~
If you are on Unix or installed PyWin32 on Windows and have multiple CPU
cores available, you can speed up the compilation by adding the ``-jX``
argument to the SCons command, where ``X`` is the number of cores that you
want to allocate to the compilation, e.g. ``scons -j4``.
Adding support for x86 devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you also want to include support for x86 devices, run the scons command
a second time with the ``android_arch=x86`` argument before building the APK
with Gradle. For example for the release template:
::
C:\godot> scons platform=android target=release
C:\godot> scons platform=android target=release android_arch=x86
C:\godot> cd platform/android/java
C:\godot\platform\android\java> gradlew build
This will create a fat binary that works in both platforms, but will add
about 6 megabytes to the APK.
Troubleshooting
~~~~~~~~~~~~~~~
It might be necessary to clean the build cache between two APK compilations,
as some users have reported issues when building the two export templates
one after the other.
Using the export templates
--------------------------
As export templates for Android, Godot needs release and debug APKs that
were compiled against the same version/commit as the editor. If you are
using official binaries for the editor, make sure to install the matching
export templates, or to build your own from the same version.
When exporting your game, Godot opens the APK, changes a few things inside,
adds your file and spits it back. It's really handy! (and required some
reverse engineering of the format).
Installing the templates
~~~~~~~~~~~~~~~~~~~~~~~~
The newly-compiled templates (android_debug.apk and android_release.apk)
must be copied to Godot's templates folder with their respective names.
The templates folder can be located in:
- Windows: ``C:\Users\[username]\AppData\Roaming\Godot\templates``
- Linux: ``/home/[username]/.godot/templates``
- Mac OSX: ``/users/[username]/.godot/templates``
.. TODO: Move these paths to a common reference page
However, if you are writing your custom modules or custom C++ code, you
might instead want to configure your APKs as custom export templates
here:
.. image:: /img/andtemplates.png
You don't even need to copy them, you can just reference the resulting
file in the ``bin\`` directory of your Godot source folder, so that the
next time you build you will automatically have the custom templates
referenced.
Troubleshooting
---------------
Application not installed
~~~~~~~~~~~~~~~~~~~~~~~~~
Android might complain the application is not correctly installed. If
so, check the following:
- Check that the debug keystore is properly generated.
- Check that jarsigner is from JDK 6, 7 or 8.
If it still fails, open a command line and run logcat:
::
C:\android-sdk\platform-tools> adb logcat
And check the output while the application is installed. Reason for
failure should be presented there.
Seek assistance if you can't figure it out.
Application exits immediately
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the application runs but exits immediately, there might be one of the
following reasons:
- Make sure to use export templates that match your editor version; if
you use a new Godot version, you *have* to update the templates too.
- libgodot_android.so is not in ``lib/armeabi-v7a`` or ``lib/armeabi``
- Device does not support armv7 (try compiling yourself for armv6)
- Device is Intel, and apk is compiled for ARM.
In any case, ``adb logcat`` should also show the cause of the error.
Compilation fails
~~~~~~~~~~~~~~~~~
On Linux systems with Kernel version 4.3 or newer, compilation may fail
with the error "pthread_create failed: Resource temporarily unavailable."
This is because of a change in the way Linux limits thread creation. But
you can change those limits through the command line. Please read this
section thoroughly before beginning.
First open a terminal, then begin compilation as usual (it may be a good
idea to run a --clean first). While compiling enter the following in
your terminal:
::
user@host:~/$ top -b -n 1 | grep scons
The output should list a scons process, with its PID as the first number
in the output. For example the PID 1077 in the output shown below:
::
user@host:~/$ top -b -n 1 | grep scons
1077 user 20 0 10544 1628 1508 S 0.000 0.027 0:00.00 grep
Now you can use another command to increase the number of processes that
scons is allowed to spawn. You can check its current limits with:
::
user@host:~/$ prlimit --pid=1077 --nproc
You can increase those limits with the command:
::
user@host:~/$ prlimit --pid=1077 --nproc=60000:60500
Obviously you should substitute the scons PID output by top and a limits
that you think suitable. These are in the form --nproc=soft:hard where
soft must be lesser than or equal to hard. See the man page for more
information.
If all went well, and you entered the prlimit command while scons was
running, then your compilation should continue without the error.

60
development/compiling/compiling_for_ios.rst Normal file
View File

@@ -0,0 +1,60 @@
.. _doc_compiling_for_ios:
Compiling for iOS
=================
.. highlight:: shell
Requirements
------------
- SCons (you can get it from macports, you should be able to run
``scons`` in a terminal when installed)
- Xcode with the iOS SDK and the command line tools.
Compiling
---------
Open a Terminal, go to the root dir of the engine source code and type:
::
$ scons p=iphone target=debug
for a debug build, or:
::
$ scons p=iphone target=release
for a release build (check ``platform/iphone/detect.py`` for the compiler
flags used for each configuration).
Alternatively, you can run
::
$ scons p=iphone arch=x86 target=debug
for a Simulator executable.
Additionally since some time Apple requires 64 bit version of application binary when you are uploading to iStore.
The best way to provide these is to create a bundle in which there are both 32bit and 64 binaries, so every device will be able to run the game.
It can be done in three steps, first compile 32 bit version, then compile 64 bit version and then use ``lipo`` to bundle them into one fat binary, all those steps can be performed with following commands:
::
$ scons p=iphone tools=no bits=32 target=release arch=arm
$ scons p=iphone tools=no bits=64 target=release arch=arm64
$ lipo -create bin/godot.iphone.opt.32 bin/godot.iphone.opt.64 -output bin/godot.iphone.opt.universal
Run
---
To run on a device or simulator, follow these instructions:
:ref:`doc_exporting_for_ios`.
Replace or add your executable to the Xcode project, and change the
"executable name" property on Info.plist accordingly if you use an
alternative build.

83
development/compiling/compiling_for_osx.rst Normal file
View File

@@ -0,0 +1,83 @@
.. _doc_compiling_for_osx:
Compiling for OSX
=================
.. highlight:: shell
Requirements
------------
For compiling under Linux or other Unix variants, the following is
required:
- Python 2.7+ (3.0 is untested as of now)
- SCons build system
- Xcode (or the more lightweight Command Line Tools for Xcode)
Compiling
---------
Start a terminal, go to the root dir of the engine source code and type:
::
user@host:~/godot$ scons platform=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.
To create an .app like in the official builds, you need to use the template
located in ``misc/dist/osx_tools.app``. Typically, for a "fat" binary that
supports both 32-bit and 64-bit architectures, and with an optimised binary
built with `scons p=osx target=release_debug`:
::
user@host:~/godot$ cp -r misc/dist/osx_tools.app ./Godot.app
user@host:~/godot$ mkdir -p Godot.app/Contents/MacOS
user@host:~/godot$ cp bin/godot.osx.opt.tools.fat Godot.app/Contents/MacOS/Godot
user@host:~/godot$ chmod +x Godot.app/Contents/MacOS/Godot
Cross-compiling
---------------
It is possible to compile for OSX in a Linux environment (and maybe
also in Windows with Cygwin). For that you will need
`OSXCross <https://github.com/tpoechtrager/osxcross>`__ to be able
to use OSX as target. First, follow the instructions to install it:
Clone the `OSXCross repository <https://github.com/tpoechtrager/osxcross>`
somewhere on your machine (or download a zip file and extract it somewhere),
e.g.:
::
user@host:~$ git clone https://github.com/tpoechtrager/osxcross.git /home/myuser/sources/osxcross
1. Follow the instructions to package the SDK:
https://github.com/tpoechtrager/osxcross#packaging-the-sdk
2. Follow the instructions to install OSXCross:
https://github.com/tpoechtrager/osxcross#installation
After that, you will need to define the ``OSXCROSS_ROOT`` as the path to
the OSXCross installation (the same place where you cloned the
repository/extracted the zip), e.g.:
::
user@host:~$ export OSXCROSS_ROOT=/home/myuser/sources/osxcross
Now you can compile with SCons like you normally would:
::
user@host:~/godot$ scons platform=osx
If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument:
::
user@host:~/godot$ scons platform=osx osxcross_sdk=darwin15

130
development/compiling/compiling_for_uwp.rst Normal file
View File

@@ -0,0 +1,130 @@
.. _doc_compiling_for_uwp:
Compiling for Universal Windows Platform
========================================
.. highlight:: shell
Requirements
------------
- SCons (see :ref:`doc_compiling_for_windows` for more details).
- Visual Studio 2015 Update 2. It may work with earlier versions. See
:ref:`doc_compiling_for_windows` about the caveats of installing it
and the various prompts.
- Windows 10 SDK (can be selected in Visual Studio installation).
- `ANGLE source <https://github.com/Microsoft/angle>`__. Use the
``ms_master`` (default) branch. Keep it in a path without spaces to
avoid problems.
Compiling
---------
You need to open a proper Visual Studio prompt for the target architecture
you want to build. Check :ref:`doc_compiling_for_windows` to see how these
prompts work.
There are three target architectures for UWP: x86 (32-bits), x64 (64-bits)
and ARM (32-bits). You can run ``vcvarsall.bat`` with ``arm`` as argument to
set the environment for this target architecture.
Set the ``ANGLE_SRC_PATH`` to the directory where you downloaded the ANGLE
source code. The build process will also build ANGLE to produce the
required DLLs for the selected architecture.
Once you're set, run the SCons command similarly to the other platforms::
C:\godot>scons platform=winrt
Creating UWP export templates
-----------------------------
To export using the editor you need to properly build package the templates.
You need all three architectures with ``debug`` and ``release`` templates to
be able to export.
Open the command prompt for one architecture and run SCons twice (once for
each target)::
C:\godot>scons platform=winrt target=release_debug
C:\godot>scons platform=winrt target=release
Repeat for the other architectures.
In the end your ``bin`` folder will have the ``.exe`` binaries with a name
like ``godot.winrt.opt.debug.32.x86.exe`` (with variations for each
target/arch).
Copy one of these to ``misc/dist/uwp_template`` inside the Godot source
folder and rename the binary to ``godot.winrt.exe``. From the ANGLE source,
under ``winrt/10/src/Release_%arch%`` (where ``%arch%`` can be ``Win32``,
``x64`` or ``ARM``), get the ``libEGL.dll`` and the ``libGLESv2.dll``,
putting them along with the executable.
Add the files in the ``uwp_template`` folder to a ZIP. Rename the resulting
Zip according to the target/architecture of the template::
winrt_x86_debug.zip
winrt_x86_release.zip
winrt_x64_debug.zip
winrt_x64_release.zip
winrt_arm_debug.zip
winrt_arm_release.zip
Move those templates to the ``templates`` folder in Godot settings path. If
you don't want to replacet the templates, you can set the "Custom Package"
property in the export window.
Running UWP apps with Visual Studio
-----------------------------------
If you want to debug the UWP port or simply run your apps without packaging
and signing, you can deploy and launch them using Visual Studio. It might be
the easiest way if you are testing on a device such as a Windows Phone or an
Xbox One.
Within the ANGLE source folder, open ``templates`` and double-click the
``install.bat`` script file. This will install the Visual Studio project
templates for ANGLE apps.
If you have not built Godot yet, open the ``winrt/10/src/angle.sln`` solution
from the ANGLE source and build it to Release/Win32 target. You may also need
to build it for ARM if you plan to run on a device. You can also use MSBuild if
you're comfortable with the command line.
Create a new Windows App project using the "App for OpenGL ES
(Windows Unversal)" project template, which can be found under the
``Visual C++/Windows/Universal`` category.
This is a base project with the ANGLE dependencies already set up. However, by
default it picks the debug version of the DLLs which usually have a very poor
performance. So in the "Binaries" filter, click in each of the DLLs there
and in the "Properties" window and change the relative path from
``Debug_Win32`` to ``Release_Win32`` (or ``Release_ARM`` for devices).
In the same "Binaries" filter, select "Add > Existing Item" and point to the
Godot executable for UWP you have. In the "Properties" window, set "Content"
to ``True`` so it's included in the project.
Right-click the ``Package.appxmanifest`` file and select "Open With... > XML
(Text) Editor". In the ``Package/Applications/Application`` element, replace
the ``Executable`` attribute from ``$targetnametoken$.exe`` to
``godot.winrt.exe`` (or whatever your Godot executable is called). Also change
the ``EntryPoint`` attribute to ``GodotWinRT.App``. This will ensure that
the Godot executable is correctly called when the app starts.
Create a folder (*not* a filter) called ``game`` in your Visual Studio project
folder and there you can put either a ``data.pck`` file or your Godot project
files. After that, make sure to include it all with the "Add > Existing Item"
command and set their "Content" property to ``True`` so they're copied to the
app.
To ease the workflow, you can open the "Solution Properties" and in the
"Configuration" section untick the "Build" option for the app. You still have
to build it at least once to generate some needed files, you can do so by
right-clicking the project (*not* the solution) in the "Solution Explorer" and
selecting "Build".
Now you can just run the project and your app should open. You can use also
the "Start Without Debugging" from the "Debug" menu (Ctrl+F5) to make it
launch faster.

175
development/compiling/compiling_for_web.rst Normal file
View File

@@ -0,0 +1,175 @@
.. _doc_compiling_for_web:
Compiling for the Web
=====================
.. highlight:: shell
Requirements
------------
To compile export templates for the Web, the following is required:
- `Emscripten SDK <http://emscripten.org/>`__ (Install in a path without
spaces, i.e. not on "Program Files")
- `Python 2.7+ <https://www.python.org/>`__ (3.0 is
untested as of now)
- `SCons <http://www.scons.org>`__ build system
Compiling
---------
Start a terminal and set the environment variable ``EMSCRIPTEN_ROOT`` to the
installation directory of Emscripten::
export EMSCRIPTEN_ROOT=~/emsdk/emscripten/master
If you are on Windows, start a regular prompt or the Emscripten Command Prompt.
Do **not** use the Developer Command Prompt nor any of the ones that come with
Visual Studio. You can set the environment variable in the system settings or
in the prompt itself::
set EMSCRIPTEN_ROOT=C:\emsdk\emscripten\master
Now go to the root directory of the engine source code and instruct SCons to
compile for JavaScript. Specify ``target`` as either ``release`` for a release
build or ``release_debug`` for a debug build::
scons platform=javascript tools=no target=release
scons platform=javascript tools=no target=release_debug
The engine will now be compiled to JavaScript by Emscripten. If all goes well,
the resulting file will be placed in the ``bin`` subdirectory. Its name is
``godot.javascript.opt.asm.js`` for release or
``godot.javascript.opt.debug.asm.js`` for debug. Additionally, two files of
the same name but with the extensions ``.js`` and ``.html.mem`` will be
generated.
Building export templates
-------------------------
After compiling, further steps are required to build the template.
The actual web export template has the form of a zip file containing at least
these 5 files:
1. ``godot.asm.js`` — This is the file that was just compiled, but under a
different name.
For the release template::
cp bin/godot.javascript.opt.asm.js godot.asm.js
For the debug template::
cp bin/godot.javascript.opt.debug.asm.js godot.asm.js
2. ``godot.js``
3. ``godot.mem`` — other files created during compilation, initially with the
same name as the ``.asm.js`` file, except ``.asm.js`` is replaced by
``.js`` for ``godot.js`` and ``.html.mem`` for
``godot.mem``.
For the release template::
cp bin/godot.javascript.opt.js godot.js
cp bin/godot.javascript.opt.html.mem godot.mem
For the debug template::
cp bin/godot.javascript.opt.debug.js godot.js
cp bin/godot.javascript.opt.debug.html.mem godot.mem
4. ``godot.html``
5. ``godotfs.js`` — Both of these files are located within the Godot Engine
repository, under ``tools/dist/html_fs/``.
::
cp tools/dist/html_fs/godot.html .
cp tools/dist/html_fs/godotfs.js .
Once these 5 files are assembled, zip them up and your export template is ready
to go. The correct name for the template file is ``javascript_release.zip`` for
the release template::
zip javascript_release.zip godot.asm.js godot.js godot.mem godotfs.js godot.html
And ``javascript_debug.zip`` for the debug template::
zip javascript_debug.zip godot.asm.js godot.js godot.mem godotfs.js godot.html
The resulting files must be placed in the ``templates`` directory in your Godot
user directory::
mv javascript_release.zip ~/.godot/templates
mv javascript_debug.zip ~/.godot/templates
If you are writing custom modules or using custom C++ code, you may want to
configure your zip files as custom export templates. This can be done in the
export GUI, using the "Custom Package" option.
There's no need to copy the templates in this case — you can simply reference
the resulting files in your Godot source folder, so the next time you build,
the custom templates will already be referenced.
Customizing the HTML page
-------------------------
Rather than the default ``godot.html`` file from the Godot Engine repository's
``tools/dist/html_fs/`` directory, it is also possible to use a custom HTML
page. This allows drastic customization of the final web presentation.
In the HTML page, the JavaScript object ``Module`` is the page's interface to
Emscripten. Check the official documentation for information on how to use it:
https://kripken.github.io/emscripten-site/docs/api_reference/module.html
The default HTML page offers an example to start off with, separating the
Emscripten interface logic in the JavaScript ``Module`` object from the page
logic in the ``Presentation`` object. Emscripten's default ``shell.html`` file
is another example, but does not use Godot's placeholders, listed below.
When exporting a game, several placeholders in the ``godot.html`` file are
substituted by values dependent on the export:
+------------------------------+-----------------------------------------------+
| Placeholder | substituted by |
+==============================+===============================================+
| ``$GODOT_JS`` | Name of the compiled Godot Engine JavaScript |
| | file |
+------------------------------+-----------------------------------------------+
| ``$GODOT_FS`` | Name of the filesystem access JavaScript |
| | file |
+------------------------------+-----------------------------------------------+
| ``$GODOT_MEM`` | Name of the memory initialization file |
+------------------------------+-----------------------------------------------+
| ``$GODOT_CANVAS_WIDTH`` | Integer specifying the initial display width |
| | of the game |
+------------------------------+-----------------------------------------------+
| ``$GODOT_CANVAS_HEIGHT`` | Integer specifying the initial display height |
| | of the game |
+------------------------------+-----------------------------------------------+
| ``$GODOT_DEBUG_ENABLED`` | String ``true`` if debugging, ``false`` |
| | otherwise |
+------------------------------+-----------------------------------------------+
| ``$GODOT_CONTROLS_ENABLED`` | String ``true`` if ``html/controls_enabled`` |
| | is enabled, ``false`` otherwise |
+------------------------------+-----------------------------------------------+
| ``$GODOT_HEAD_TITLE`` | Title of the page, normally used as content |
| | of the HTML ``<title>`` element |
+------------------------------+-----------------------------------------------+
| ``$GODOT_HEAD_INCLUDE`` | Custom string to include just before the end |
| | of the HTML ``<head>`` element |
+------------------------------+-----------------------------------------------+
| ``$GODOT_STYLE_FONT_FAMILY`` | CSS format ``font-family`` to use, without |
| | terminating semicolon |
+------------------------------+-----------------------------------------------+
| ``$GODOT_STYLE_INCLUDE`` | Custom string to include just before the end |
| | of the page's CSS |
+------------------------------+-----------------------------------------------+
The first five of the placeholders listed should always be implemented in the
HTML page, since they are important for the correct presentation of the game.
The other placeholders are optional.
Finally, the custom HTML page is installed by replacing the existing
``godot.html`` file in the export template with the new one, retaining the name
of the original.

430
development/compiling/compiling_for_windows.rst Normal file
View File

@@ -0,0 +1,430 @@
.. _doc_compiling_for_windows:
Compiling for Windows
=====================
.. highlight:: shell
Requirements
------------
For compiling under Windows, the following is required:
- Visual C++, `Visual
Studio Community <https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx>`__
(recommended), at least the 2013 version (12.0) up to 2015 (14.0).
**Make sure you read Installing Visual Studio caveats below or you
will have to run/download the installer again.**
- `Python 2.7+ <https://www.python.org/downloads/>`__ (3.0 is
untested as of now). Using the 32-bits installer is recommended.
- `Pywin32 Python Extension <https://sourceforge.net/projects/pywin32/files/pywin32/>`__
for parallel builds (which increase the build speed by a great factor).
- `SCons <http://www.scons.org>`__ 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 (typically in the ``Scripts`` folder) and
provides a batch 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.
To check whether you have installed Python and SCons correctly, you can
type ``python --version`` and ``scons --version`` into the standard
Windows Command Prompt (cmd.exe).
If commands above do not work, make sure you add Python to your PATH
environment variable after installing it, and check again.
Setting up Pywin32
-------------------------
Pywin32 is required for -j (parallel) builds for multiple cores (for a
32 bit Python version). If SCons is issuing a warning about Pywin32
after parsing SConstruct build instructions, when begining to build,
you need to install it properly from the correct installer executable
for your python version `located at Sourceforge. <https://sourceforge.net/projects/pywin32/files/pywin32/>`__
For example, if you installed Python 2.7 32 bit version, you would want
to install the latest version of Pywin32 (as of writting Build 220) that
is built for the mentioned version of Python... That executable installer
would be named "pywin32-220.win32-py2.7.exe".
Amd64 version of Pywin32 is for a 64 bit version of Python
"pywin32-220.win-amd64-py2.7.exe". Change the "py" number to install for
your version of python (check via ``python --version`` mentioned above).
Installing Visual Studio caveats
-----------------------------------
If installing VS 2015, make sure to run **Custom** installation, not
**Typical** and select C++ as language there (and any other things you might
need). The installer does not install C++ by default. C++ was the
`only language made optional <https://blogs.msdn.microsoft.com/vcblog/2015/07/24/setup-changes-in-visual-studio-2015-affecting-c-developers/>`__
in VS2015.
If you have already made the mistake of installing a **Typical**,
installation, rerun the executable installer you downloaded from
internet, it will give you a **Modify** Button option. Running the
install from Add/Remove programs will only give you the "Repair" option,
which will do nothing for your problem.
If you're using Express, make sure you get/have a version that can
compile for ***C++, Desktop***.
Downloading Godot's source
--------------------------
`Godot's <https://github.com/godotengine/godot>`__ source is hosted on
GitHub. Downloading it (cloning) via `Git <https://git-scm.com/>`__ is recommended.
The tutorial will presume from now on that you placed the source into
``C:\godot``.
Compiling
---------
SCons will not be able out of the box to compile from the standard
Windows "Command Prompt" (cmd.exe) because SCons and Visual C++ compiler
will not be able to locate environment variables and executables they
need for compilation.
Therefore, you need to start a Visual Studio command prompt. It sets up
environment variables needed by SCons to locate the compiler.
It should be called similar to one of the below names (for your
respective version of Visual Studio):
* "Developer Command Prompt for VS2013"
* "VS2013 x64 Native Tools Command Prompt"
* "VS2013 x86 Native Tools Command Prompt"
* "VS2013 x64 Cross Tools Command Prompt"
* "VS2013 x86 Cross Tools Command Prompt"
You should be able to find at least the Developer Command Prompt for
your version of Visual Studio in your start menu.
However Visual Studio sometimes seems to not install some of the above
shortcuts, except the Developer Console at these locations that are
automatically searched by the start menu search option:
::
Win 7:
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2015\Visual Studio Tools
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2013\Visual Studio Tools
If you found the Developer Console, it will do for now to create a 32
bit version of Godot, but if you want the 64 bit version, you might need
to setup the prompts manually for easy access.
If you don't see some of the shortcuts, "How the prompts actually work"
section below will explain how to setup these prompts if you need them.
About the Developer/Tools Command Prompts and the Visual C++ compiler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is a few things you need to know about these consoles and the
Visual C++ compiler.
Your Visual Studio installation will ship with several Visual C++
compilers, them being more or less identical, however each cl.exe
(Visual C++ compiler) will compile Godot for a different architecture
(32 or 64 bit, ARM compiler is not supported).
The **Developer Command Prompt** will build a 32 bit version of Godot by
using the 32 bit Visual C++ compiler.
**Native Tools** Prompts (mentioned above) are used when you want the
32bit cl.exe to compile a 32 bit executable (x86 Native Tools
Command Prompt). For the 64 bit cl.exe, it will compile a 64 bit
executable (x64 Native Tools Command Prompt).
The **Cross Tools** are used when your Windows is using one architecture
(32 bit, for example) and you need to compile to a different
architecture (64 bit). As you might be familiar, 32 bit Windows can not
run 64 bit executables, but you still might need to compile for them.
For example:
* "VS2013 x64 Cross Tools Command Prompt" will use a 32 bit cl.exe that
will compile a 64 bit application.
* "VS2013 x86 Cross Tools Command Prompt" will use a 64 bit cl.exe that
will compile a 32 bit application. This one is useful if you are
running a 32 bit Windows.
On a 64 bit Windows, you can run any of above prompts and compilers
(cl.exe executables) because 64 bit windows can run any 32 bit
application. 32 bit Windows can not run 64 bit executables, so the
Visual Studio installer will not even install shortcuts for some of
these prompts.
Note that you need to choose the **Developer Console** or the correct
**Tools Prompt** to build Godot for the correct architecture. Use only
Native Prompts if you are not sure yet what exactly Cross Compile
Prompts do.
Running SCons
~~~~~~~~~~~~
Once inside the **Developer Console/Tools Console Prompt**, go to the
root directory of the engine source code and type:
::
C:\godot> scons platform=windows
Tip: if you installed "Pywin32 Python Extension" you can append the -j
command to instruct SCons to run parallel builds like this:
::
C:\godot> scons -j6 platform=windows
In general, it is OK to have at least as many threads compiling Godot as
you have cores in your CPU, if not one or two more, I use -j6
(six threads) for my 4 core CPU, your mileage may vary. Feel free to add
-j option to any SCons command you see below if you setup the
"Pywin32 Python Extension".
If all goes well, the resulting binary executable will be placed in
``C:\godot\bin\`` with the name of ``godot.windows.tools.32.exe`` or
``godot.windows.tools.64.exe``. SCons will automatically detect what
compiler architecture the environment (the prompt) is setup for and will
build a corresponding executable.
This executable file contains the whole engine and runs without any
dependencies. Executing it will bring up the project manager.
How the prompts actually work
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Visual Studio command prompts are just shortcuts that call the
standard Command Prompt and have it run a batch file before giving you
control. The batch file itself is called **vcvarsall.bat** and it sets up
environment variables, including the PATH variable, so that the correct
version of the compiler can be run.The Developer Command Prompt calls a
different file called **VsDevCmd.bat** but none of the other tools that
this batch file enables are needed by Godot/SCons.
Since you are probably using VS2013 or VS2015, if you need to recreate
them manually, use the below folders, or place
them on the desktop/taskbar:
::
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2015\Visual Studio Tools
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2013\Visual Studio Tools
Start the creation of the shortcut by pressing the ``right mouse
button/New/Shortcut`` in an empty place in your desired location.
Then copy one of these commands below for the corresponding tool you
need into the "Path" and "Name" sections of the shortcut creation
wizard, and fix the path to the batch file if needed.
* VS2013 is in the "Microsoft Visual Studio 12.0" folder.
* VS2015 is in the "Microsoft Visual Studio 14.0" folder.
* etc.
::
Name: Developer Command Prompt for VS2013
Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\VsDevCmd.bat""
Name: VS2013 x64 Cross Tools Command Prompt
Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" x86_amd64
Name: VS2013 x64 Native Tools Command Prompt
Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" amd64
Name: VS2013 x86 Native Tools Command Prompt
Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" x86
Name: VS2013 x86 Cross Tools Command Prompt
Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" amd64_x86
After you create the shortcut, in the shortcut's properties, that you
can access by right clicking with your mouse on the shortcut itself, you
can choose the starting directory of the command prompt ("Start in"
field).
Some of these shortcuts (namely the 64 bit compilers) seem to not be
available in the Express edition of Visual Studio or Visual C++. Before
recreating the commands, make sure that cl.exe executables are present
in one of these locations, they are the actual compilers for the
arhitecture you want to build from the command prompt.
::
x86 (32bit) cl.exe
C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\cl.exe
x86 (32bit) cl.exe for crosscompiling to 64bit.
C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\x86_amd64\cl.exe
x64 (64bit) cl.exe
C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64\cl.exe
x64 (64bit) cl.exe for crosscompiling to 32bit.
C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64_x86\cl.exe
In case you are wondering what these prompt shortcuts do, they call the
standard cmd.exe with \\k option and have it run a batch file...
::
%comspec% - path to cmd.exe
\k - keep alive option of the command prompt
remainder - command to run via cmd.exe
cmd.exe \k(eep cmd.exe alive after commands behind this option run) ""runme.bat"" with_this_option
How to run an automated build of Godot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you need to just run the compilation process via a batch file or
directly in the vanilla Windows Command Prompt you need to do the
following command:
::
"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86
with one of the following parameters:
* x86 (32 bit cl.exe to compile for the 32 bit architecture)
* amd64 (64 bit cl.exe to compile for the 64 bit architecture)
* x86_amd64 (32 bit cl.exe to compile for the 64 bit architecture)
* amd64_x86 (64 bit cl.exe to compile for the 32 bit architecture)
and after that one, you can run SCons:
::
scons platform=windows
or you can do them together:
::
32 bit Godot
"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86 && scons platform=windows
64 bit Godot
"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" amd64 && scons platform=windows
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.
You can create a Visual Studio solution via SCons by running SCons with
the vsproj=yes parameter, like this:
::
scons p=windows vsproj=yes
You will be able to open Godot's source in a Visual Studio solution now,
and able to build Godot via the Visual Studio **Build** button. However,
make sure that you have installed Pywin so that parallel (-j) builds
work properly.
If you need to edit the compilation commands, they are located in
"Godot" project settings, NMAKE sheet. SCons is called at the very end of
the commands. If you make a mistake, copy the command from one of the
other build configurations (debug, release_debug, release) or
architectures (Win32/x64). They are equivalent.
Cross-compiling for Windows from other operating systems
---------------
If you are a Linux or Mac user, you need to install mingw32 and
mingw-w64. Under Ubuntu or Debian, just run the following commands:
::
apt-get install mingw32 mingw-w64
If you are using another distro, SCons will check for the following
binaries:
::
i586-mingw32msvc-gcc
i686-w64-mingw32-gcc
If the binaries are named or located somewhere else, export the
following env variables:
::
export MINGW32_PREFIX="/path/to/i586-mingw32msvc-"
export MINGW64_PREFIX="/path/to/i686-w64-mingw32-"
To make sure you are doing things correctly, executing the following in
the shell should result in a working compiler:
::
user@host:~$ ${MINGW32_PREFIX}gcc
gcc: fatal error: no input files
Creating Windows export templates
---------------------------------
Windows export templates are created by compiling Godot as release, with
the following flags:
- (using Mingw32 command prompt, using the bits parameter)
::
C:\godot> scons platform=windows tools=no target=release bits=32
C:\godot> scons platform=windows tools=no target=release_debug bits=32
- (using Mingw-w64 command prompt, using the bits parameter)
::
C:\godot> scons platform=windows tools=no target=release bits=64
C:\godot> scons platform=windows tools=no target=release_debug bits=64
- (using the Visual Studio command prompts for the correct
architecture, notice the lack of bits parameter)
::
C:\godot> scons platform=windows tools=no target=release
C:\godot> scons platform=windows tools=no target=release_debug
If you plan on replacing the standard templates, copy these to:
::
C:\USERS\YOURUSER\AppData\Roaming\Godot\Templates
With the following names:
::
windows_32_debug.exe
windows_32_release.exe
windows_64_debug.exe
windows_64_release.exe
However, if you are writing your custom modules or custom C++ code, you
might instead want to configure your binaries as custom export templates
here:
.. image:: /img/wintemplates.png
You don't even need to copy them, you can just reference the resulting
files in the ``bin\`` directory of your Godot source folder, so the next
time you build you automatically have the custom templates referenced.

136
development/compiling/compiling_for_x11.rst Normal file
View File

@@ -0,0 +1,136 @@
.. _doc_compiling_for_x11:
Compiling for X11 (Linux, *BSD)
===============================
.. highlight:: shell
Requirements
------------
For compiling under Linux or other Unix variants, the following is
required:
- GCC < 6 or Clang (**warning:** see note below regarding GCC 6).
- Python 2.7+ (3.0 is untested as of now)
- SCons build system
- pkg-config (used to detect the dependencies below)
- X11, Xcursor, Xinerama and XRandR development libraries
- MesaGL development libraries
- ALSA development libraries
- PulseAudio development libraries (for sound support)
- Freetype (for the editor)
- OpenSSL (for HTTPS and TLS)
- libudev-dev (optional, for gamepad support)
Known issues with GCC 6
^^^^^^^^^^^^^^^^^^^^^^^
There are known optimisation issues when using GCC 6 (both to compile for X11 and to cross-compile for Windows with MinGW). Until those issues are fixed in Godot's source, or the compiler is made more forgiving again, it is advised not to use GCC 6 to compile Godot as release builds will trigger crashes.
If your distribution provides GCC 6 by default (e.g. Arch or Ubuntu 16.10), you may have to install an older version or Clang (both should be provided in the repositories). You can then force the use of another compiler version via the `CC` and `CXX` scons arguments (e.g. `scons p=x11 CC=gcc-5 CXX=g++-5` if your distribution provides those binaries in its PATH). You can also use `llvm=yes` instead to force the usage of Clang over GCC.
Distro-specific oneliners
^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------+------------------------------------------------------------------------------------------------------------+
| **Fedora** | :: |
| | |
| | sudo dnf install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \ |
| | mesa-libGL-devel alsa-lib-devel pulseaudio-libs-devel freetype-devel openssl-devel libudev-devel \ |
| | mesa-libGLU-devel |
+---------------+------------------------------------------------------------------------------------------------------------+
| **FreeBSD** | :: |
| | |
| | sudo pkg install scons pkg-config xorg-libraries libXcursor libXrandr xineramaproto libglapi libGLU \ |
| | freetype2 openssl |
+---------------+------------------------------------------------------------------------------------------------------------+
| **Mageia** | :: |
| | |
| | urpmi scons pkgconfig "pkgconfig(alsa)" "pkgconfig(freetype2)" "pkgconfig(glu)" "pkgconfig(libpulse)" \|
| | "pkgconfig(openssl)" "pkgconfig(udev)" "pkgconfig(x11)" "pkgconfig(xcursor)" "pkgconfig(xinerama)"\|
| | "pkgconfig(xrandr)" "pkgconfig(zlib)" |
+---------------+------------------------------------------------------------------------------------------------------------+
| **Ubuntu** | :: |
| | |
| | sudo apt-get install build-essential scons pkg-config libx11-dev libxcursor-dev libxinerama-dev \ |
| | libgl1-mesa-dev libglu-dev libasound2-dev libpulse-dev libfreetype6-dev libssl-dev libudev-dev \ |
| | libxrandr-dev |
+---------------+------------------------------------------------------------------------------------------------------------+
| **Arch** | :: |
| | |
| | pacman -S scons libxcursor libxinerama libxrandr mesa glu alsa-lib pulseaudio freetype2 |
+---------------+------------------------------------------------------------------------------------------------------------+
| **Gentoo** | :: |
| | |
| | emerge -an dev-util/scons x11-libs/libX11 x11-libs/libXcursor x11-libs/libXinerama media-libs/mesa \ |
| | media-libs/glu media-libs/alsa-lib media-sound/pulseaudio media-libs/freetype |
+---------------+------------------------------------------------------------------------------------------------------------+
Compiling
---------
Start a terminal, go to the root dir of the engine source code and type:
::
user@host:~/godot$ scons platform=x11
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.
If you wish to compile using Clang rather than GCC, use this command:
::
user@host:~/godot$ scons platform=x11 use_llvm=yes
Building export templates
-------------------------
To build X11 (Linux, *BSD) export templates, run the build system with the
following parameters:
- (32 bits)
::
user@host:~/godot$ scons platform=x11 tools=no target=release bits=32
user@host:~/godot$ scons platform=x11 tools=no target=release_debug bits=32
- (64 bits)
::
user@host:~/godot$ scons platform=x11 tools=no target=release bits=64
user@host:~/godot$ scons platform=x11 tools=no target=release_debug bits=64
Note that cross compiling for the opposite bits (64/32) as your host
platform is not always straight-forward and might need a chroot environment.
To create standard export templates, the resulting files must be copied to:
::
/home/youruser/.godot/templates
and named like this (even for *BSD which is seen as "Linux X11" by Godot):
::
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
However, if you are writing your custom modules or custom C++ code, you
might instead want to configure your binaries as custom export templates
here:
.. image:: /img/lintemplates.png
You don't even need to copy them, you can just reference the resulting
files in the bin/ directory of your Godot source folder, so the next
time you build you automatically have the custom templates referenced.

159
development/compiling/cross-compiling_for_ios_on_linux.rst Normal file
View File

@@ -0,0 +1,159 @@
.. _doc_cross-compiling_for_ios_on_linux:
Cross-compiling for iOS on Linux
================================
.. highlight:: shell
The procedure for this is somewhat complex and requires a lot of steps,
but once you have the environment properly configured it will be easy to
compile Godot for iOS anytime you want.
Disclaimer
----------
While it is possible to compile for iOS on a Linux environment, Apple is
very restrictive about the tools to be used (specially hardware-wise),
allowing pretty much only their products to be used for development. So
this is **not official**. However, a `statement from Apple in 2010
<http://www.apple.com/pr/library/2010/09/09Statement-by-Apple-on-App-Store-Review-Guidelines.html>`__
says they relaxed some of the `App Store review guidelines
<https://developer.apple.com/app-store/review/guidelines/>`__
to allow any tool to be used, as long as the resulting binary does not
download any code, which means it should be OK to use the procedure
described here and cross-compiling the binary.
Requirements
------------
- `XCode with the iOS SDK <https://developer.apple.com/xcode/download>`__
(a dmg image)
- `Clang >= 3.5 <http://clang.llvm.org>`__ for your development
machine installed and in the ``PATH``. It has to be version >= 3.5
to target ``arm64`` architecture.
- `Fuse <http://fuse.sourceforge.net>`__ for mounting and umounting
the dmg image.
- `darling-dmg <https://github.com/darlinghq/darling-dmg>`__, which
needs to be built from source. The procedure for that is explained
below.
- For building darling-dmg, you'll need the development packages of
the following libraries: fuse, icu, openssl, zlib, bzip2.
- `cctools-port <https://github.com/tpoechtrager/cctools-port>`__
for the needed build tools. The procedure for building is quite
peculiar and is described below.
- This also has some extra dependencies: automake, autogen, libtool.
Configuring the environment
---------------------------
darling-dmg
~~~~~~~~~~~
Clone the repository on your machine:
::
$ git clone https://github.com/darlinghq/darling-dmg.git
Build it:
::
$ cd darling-dmg
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make -j 4 # The number is the amount of cores your processor has, for faster build
$ cd ../..
Preparing the SDK
~~~~~~~~~~~~~~~~~
Mount the XCode image:
::
$ mkdir xcode
$ ./darling-dmg/build/darling-dmg /path/to/Xcode_7.1.1.dmg xcode
[...]
Everything looks OK, disk mounted
Extract the iOS SDK:
::
$ mkdir -p iPhoneSDK/iPhoneOS9.1.sdk
$ cp -r xcode/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/* iPhoneSDK/iPhoneOS9.1.sdk
$ cp -r xcode/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/* iPhoneSDK/iPhoneOS9.1.sdk/usr/include/c++
$ fusermount -u xcode # unmount the image
Pack the SDK:
::
$ cd iPhoneSDK
$ tar -cf - * | xz -9 -c - > iPhoneOS9.1.sdk.tar.xz
Toolchain
~~~~~~~~~
Build cctools:
::
$ git clone https://github.com/tpoechtrager/cctools-port.git
$ cd cctools-port/usage_examples/ios_toolchain
$ ./build.sh /path/iPhoneOS9.1.sdk.tar.xz arm64
Copy the tools to a nicer place. Note that the SCons scripts for
building will look under ``usr/bin`` inside the directory you provide
for the toolchain binaries, so you must copy to such subdirectory, akin
to the following commands:
::
$ mkdir -p /home/user/iostoolchain/usr
$ cp -r target/bin /home/user/iostoolchain/usr/
Now you should have the iOS toolchain binaries in
``/home/user/iostoolchain/usr/bin``.
Compiling Godot for iPhone
--------------------------
Once you've done the above steps, you should keep two things in your
environment: the built toolchain and the iPhoneOS SDK directory. Those
can stay anywhere you want since you have to provide their paths to the
SCons build command.
For the iPhone platform to be detected, you need the ``OSXCROSS_IOS``
environment variable defined to anything.
::
$ export OSXCROSS_IOS=anything
Now you can compile for iPhone using SCons like the standard Godot
way, with some additional arguments to provide the correct paths:
::
$ scons -j 4 platform=iphone arch=arm target=release_debug IPHONESDK="/path/to/iPhoneSDK" IPHONEPATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-"
$ scons -j 4 platform=iphone arch=arm64 target=release_debug IPHONESDK="/path/to/iPhoneSDK" IPHONEPATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-"
Producing fat binaries
~~~~~~~~~~~~~~~~~~~~~~
Apple requires a fat binary with both architectures (``armv7`` and
``arm64``) in a single file. To do this, use the
``arm-apple-darwin11-lipo`` executable. The following example assumes
you are in the root Godot source directory:
::
$ /path/to/iostoolchain/usr/bin/arm-apple-darwin11-lipo -create bin/godot.iphone.opt.debug.arm bin/godot.iphone.opt.debug.arm64 -output bin/godot.iphone.opt.debug.fat
Then you will have an iOS fat binary in ``bin/godot.iphone.opt.debug.fat``.

220
development/compiling/introduction_to_the_buildsystem.rst Normal file
View File

@@ -0,0 +1,220 @@
.. _doc_introduction_to_the_buildsystem:
Introduction to the buildsystem
===============================
.. highlight:: shell
Scons
-----
Godot uses `Scons <http://www.scons.org>`__ to build. We love it, we are
not changing it for anything else. We are not even sure other build
systems are up to the task of building Godot. We constantly get requests
to move the build system to CMake, or Visual Studio, but this is not
going to happen. There are many reasons why we have chosen SCons over
other alternatives and are listed as follows:
- Godot can be compiled for a dozen different platforms. All PC
platforms, all mobile platforms, many consoles, and many web-based
platforms (such as HTML5 and Chrome PNACL).
- Developers often need to compile for several of the platforms **at
the same time**, or even different targets of the same platform. They
can't afford reconfiguring and rebuilding the project each time.
SCons can do this with no sweat, without breaking the builds.
- SCons will *never* break a build no matter how many changes,
configurations, additions, removals etc. You have more chances to die
struck by lightning than needing to clean and rebuild in SCons.
- Godot build process is not simple. Several files are generated by
code (binders), others are parsed (shaders), and others need to offer
customization (plugins). This requires complex logic which is easier
to write in an actual programming language (like Python) rather than
using a mostly macro-based language only meant for building.
- Godot build process makes heavy use of cross compiling tools. Each
platform has a specific detection process, and all these must be
handled as specific cases with special code written for each.
So, please get at least a little familiar with it if you are planning to
build Godot yourself.
Platform selection
------------------
Godot's build system will begin by detecting the platforms it can build
for. If not detected, the platform will simply not appear on the list of
available platforms. The build requirements for each platform are
described in the rest of this tutorial section.
Scons is invoked by just calling ``scons``.
However, this will do nothing except list the available platforms, for
example:
::
user@host:~/godot$ scons
scons: Reading SConscript files ...
No valid target platform selected.
The following were detected:
android
server
javascript
windows
x11
Please run scons again with argument: platform=<string>
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.
To build for a platform (for example, x11), run with the ``platform=`` (or just
``p=`` to make it short) argument:
::
user@host:~/godot$ scons platform=x11
This will start the build process, which will take a while. If you want
scons to build faster, use the ``-j <cores>`` parameter to specify how many
cores will be used for the build. Or just leave it using one core, so you
can use your computer for something else :)
Example for using 4 cores:
::
user@host:~/godot$ scons platform=x11 -j 4
Resulting binary
----------------
The resulting binaries will be placed in the bin/ subdirectory,
generally with this naming convention:
::
godot.<platform>.[opt].[tools/debug].<architecture>[extension]
For the previous build attempt the result would look like this:
::
user@host:~/godot$ ls bin
bin/godot.x11.tools.64
This means that the binary is for X11, is not optimized, has tools (the
whole editor) compiled in, and is meant for 64 bits.
A Windows binary with the same configuration will look like this.
::
C:\GODOT> DIR BIN/
godot.windows.tools.64.exe
Just copy that binary to wherever you like, as it self-contains the
project manager, editor and all means to execute the game. However, it
lacks the data to export it to the different platforms. For that the
export templates are needed (which can be either downloaded from
`godotengine.org <http://godotengine.org>`, or you can build them yourself).
Aside from that, there are a few standard options that can be set in all
build targets, and will be explained as follows.
Tools
-----
Tools are enabled by default in al PC targets (Linux, Windows, OSX),
disabled for everything else. Disabling tools produces a binary that can
run projects but that does not include the editor or the project
manager.
::
scons platform=<platform> 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). Official binaries use this configuration.
- **release**: Build without symbols, with optimization and with little
to no runtime checks. This target can't be used together with
tools=yes, as the tools require some debug functionality and run-time
checks to run.
::
scons platform=<platform> target=debug/release_debug/release
This flag appends ".debug" suffix (for debug), or ".tools" (for debug
with tools enabled). When optimization is enabled (release) it appends
the ".opt" suffix.
Bits
----
Bits is meant to control the CPU or OS version intended to run the
binaries. It works mostly on desktop platforms and ignored everywhere
else.
- **32**: Build binaries for 32 bits platform.
- **64**: Build binaries for 64 bits platform.
- **default**: Built whatever the build system feels is best. On Linux
this depends on the host platform (if not cross compiling), while on
Windows and Mac it defaults to produce 32 bits binaries unless 64
bits is specified.
::
scons platform=<platform> bits=default/32/64
This flag appends ".32" or ".64" suffixes to resulting binaries when
relevant.
Export templates
----------------
Official export templates are downloaded from the Godot Engine site:
`godotengine.org <http://godotengine.org>`. However, you might want
to build them yourself (in case you want newer ones, you are using custom
modules, or simply don't trust your own shadow).
If you download the official export templates package and unzip it, you
will notice that most are just optimized binaries or packages for each
platform:
::
android_debug.apk
android_release.apk
javascript_debug.zip
javascript_release.zip
linux_server_32
linux_server_64
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
osx.zip
version.txt
windows_32_debug.exe
windows_32_release.exe
windows_64_debug.exe
windows_64_release.exe
To create those yourself, just follow the instructions detailed for each
platform in this same tutorial section. Each platform explains how to
create its own template.
If you are working for multiple platforms, OSX is definitely the best
host platform for cross compilation, since you can cross-compile for
almost every target (except for winrt). Linux and Windows come in second
place, but Linux has the advantage of being the easier platform to set
this up.

56
development/compiling/packaging_godot.rst Normal file
View File

@@ -0,0 +1,56 @@
.. _doc_packaging_godot:
Packaging Godot
===============
Starting with 2.0, Godot has features to make it easier to package it for application repositories.
Default behaviour
-----------------
Per default, Godot stores all settings and installed templates in a per-user directory.
First Godot checks the ``APPDATA`` environment variable. If it exists, the per-user directory
is the "Godot" subdirectory of ``$APPDATA``.
If ``APPDATA`` doesn't exist, Godot checks the ``HOME`` environment variable. The per-user
directory is then the ".godot" subdir of ``$HOME``.
This meets common operating system standards.
Global template path (Unix only)
--------------------------------
The ``unix_global_settings_path`` build variable is meant for Unix/Linux distro packagers
who want to package export templates together with godot. It allows to put the export
templates on a hardcoded path.
To use it, pass the desired path via the scons ``unix_global_settings_path`` build variable
when building the editor. The export templates then live at the "templates" subdirectory
of the path specified.
Templates installed at the per-user location still override the system wide templates.
This option is only available on unix based platforms.
Self contained mode
-------------------
The self contained mode can be used to package godot for distribution systems where godot
doesn't live at a fixed location. If the godot editor finds a ``._sc_`` file in the directory
the executable is located, godot will continue in "self contained mode".
In self contained mode, all config files are located next to the executable in a directory
called ``editor_data``. Godot doesn't read or write to the per-user location anymore.
The contents of the ``._sc_`` file (when not empty) are read with the ConfigFile api (same
format as ``engine.cfg``, etc). So far it can contain a list of pre-loaded project in this
format:
::
[init_projects]
list=["demos/2d/platformer", "demos/2d/isometric"]
The paths are relative to the executable location, and will be added to the file ``editor_settings.xml``
when this is created for the first time.

183
development/cpp/configuring_an_ide.rst Normal file
View File

@@ -0,0 +1,183 @@
.. _doc_configuring_an_ide:
Configuring an IDE
==================
We assume that you already `cloned <https://github.com/godotengine/godot>`_
and :ref:`compiled <toc-compiling>` Godot.
Kdevelop
--------
It is a free, open source IDE (Integrated Development Environment)
for Linux, Solaris, FreeBSD, Mac OS X and other Unix flavors.
You can find a video tutorial `here <https://www.youtube.com/watch?v=yNVoWQi9TJA>`_.
Or you may follow this text version tutorial.
Start by opening Kdevelop and choosing "open project".
.. image:: /img/kdevelop_newproject.png
Choose the directory where you cloned Godot.
.. image:: /img/kdevelop_openproject.png
For the build system, choose "custom build system".
.. image:: /img/kdevelop_custombuild.png
Now that the project has been imported, open the project configuration.
.. image:: /img/kdevelop_openconfig.png
Add the following includes/imports:
::
. // a dot to indicate the root of the Godot project
core/
core/os/
core/math/
tools/
drivers/
platform/x11/ // make that platform/osx/ is you're using OS X
.. image:: /img/kdevelop_addincludes.png
Apply the changes then switch to the "Custom Buildsystem" tab.
Leave the build directory blank. Enable build tools and add ``scons``
as the executable and add ``platform=x11 target=debug`` (``platform=osx``
if you're on OS X).
.. image:: /img/kdevelop_buildconfig.png
Next we need to tell KDevelop where to find the binary.
From the "run" menu, choose "Configure Launches".
.. image:: /img/kdevelop_configlaunches.png
Click "Add new" if no launcher exists. Then add the path to your
executable in the executable section. Your executable should be located
in the ``bin/`` sub-directory and should be named something like
``godot.x11.tools.64`` (the name could be different depending on your
platform and depending on your build options).
.. image:: /img/kdevelop_configlaunches2.png
That's it! Now you should be good to go :)
Eclipse
-------
TODO.
QtCreator
---------
Importing the project
^^^^^^^^^^^^^^^^^^^^^
- Choose *New Project* -> *Import Project* -> *Import Existing Project*.
- Set the path to your Godot root directory and enter the project name.
- Here you can choose which folders and files will be visible to the project. C/C++ files
are added automatically. Potentially useful additions: \*.py for buildsystem files, \*.java for Android development,
\*.mm for OSX. Click "Next".
- Click *Finish*.
- Add a line containing ``.`` to *project_name.includes* to get working code completion.
Build and run
^^^^^^^^^^^^^
Build configuration:
- Click on *Projects* and open the *Build* tab.
- Delete the pre-defined ``make`` build step.
- Click *Add Build Step* -> *Custom Process Step*.
- Type ``scons`` in the *Command* field.
- Fill the *Arguments* field with your compilation options. (e.g.: ``p=x11 target=debug -j 4``)
Run configuration:
- Open the *Run* tab.
- Point the *Executable* to your compiled Godot binary (e.g: ``%{buildDir}\bin\godot.windows.tools.64.exe``)
- If you want to run a specific game or project, point *Working directory* to the game directory.
- If you want to run the editor, add ``-e`` to the *Command line arguments* field.
Xcode
-----
Project Setup
^^^^^^^^^^^^^
- Create an |xcode external build| project anywhere
- Set the *Build tool* to the path to scons
Modify Build Target's |xcode Info Tab|:
- Set *Arguments* to something like: platform=osx tools=yes bits=64 target=debug
- Set *Directory* to the path to Godot's source folder. Keep it blank if project is already there.
- You may uncheck *Pass build settings in environment*
Add a Command Line Target:
- Go to |xcode File > New > Target...| and add a new |xcode command line target|
- Name it something so you know not to compile with this target
- e.g. GodotXcodeIndex
- Goto the newly created target's *Build Settings* tab and search for *Header Search Paths*
- Set *Header Search Paths* to an absolute path to Godot's source folder
- Make it recursive by adding two \*'s to the end of the path
- e.g. /Users/me/repos/godot-source/\**
Add Godot Source to the Project:
- Drag and drop godot source into project file browser.
- |xcode Uncheck| *Create External Build System*
- Click Next
- |xcode Select| *create groups*
- Check off only your command line target in the *Add to targets* section
- Click finish. Xcode will now index the files.
- Grab a cup of coffee... Maybe make something to eat, too
- You should have jump to definition, auto completion, and full syntax highlighting when it is done.
Scheme Setup
^^^^^^^^^^^^
Edit Build Scheme of External Build Target:
- Open scheme editor of external build target
- Expand the *Build* menu
- Goto *Post Actions*
- Add a new script |xcode run action|
- Write a script that gives the binary a name that Xcode will recognize
- e.g. ln -f "$SRCROOT"/bin/godot.osx.tools.64 "$SRCROOT"/bin/godot
- Build the external build target
Edit Run Scheme of External Build Target:
- Open the scheme editor again
- |xcode Click Run|
- Set the *Executable* to the file you linked in your post build action script
- Check *Debug executable* if it isn't already
- You can go to *Arguments* tab and add an -e and a -path to a project to debug the editor
not the project selection screen
Test It:
- set a breakpoint in platform/osx/godot_main_osx.mm
- it should break at the point!
.. |xcode external build| replace:: :download:`external build </img/xcode_1_create_external_build_project.png>`
.. |xcode Info Tab| replace:: :download:`Info Tab </img/xcode_2_configure_scons.png>`
.. |xcode File > New > Target...| replace:: :download:`File > New > Target... </img/xcode_3_add_new_target.png>`
.. |xcode command line target| replace:: :download:`command line target </img/xcode_4_select_command_line_target.png>`
.. |xcode Uncheck| replace:: :download:`Uncheck </img/xcode_5_after_add_godot_source_to_project.png>`
.. |xcode Select| replace:: :download:`Select </img/xcode_6_after_add_godot_source_to_project_2.png>`
.. |xcode run action| replace:: :download:`run action </img/xcode_7_setup_build_post_action.png>`
.. |xcode Click Run| replace:: :download:`Click Run </img/xcode_8_setup_run_scheme.png>`
Other editors (vim, emacs, Atom...)
-----------------------------------
TODO.

236
development/cpp/core_types.rst Normal file
View File

@@ -0,0 +1,236 @@
.. _doc_core_types:
Core types
==========
Godot has a rich set of classes and templates that compose its core,
and everything is built upon them.
This reference will try to list them in order for their better
understanding.
Definitions
-----------
Godot uses the standard C98 datatypes, such as ``uint8_t``,
``uint32_t``, ``int64_t``, etc. which are nowadays supported by every
compiler. Reinventing the wheel for those is not fun, as it makes code
more difficult to read.
In general, care is not taken to use the most efficient datatype for a
given task unless using large structures or arrays. ``int`` is used
through most of the code unless necessary. This is done because nowadays
every device has at least a 32 bits bus and can do such operations in
one cycle. It makes code more readable too.
For files or memory sizes, ``size_t`` is used, which is warranted to be
64 bits.
For Unicode characters, CharType instead of wchar_t is used, because
many architectures have 4 bytes long wchar_t, where 2 bytes might be
desired. However, by default, this has not been forced and CharType maps
directly to wchar_t.
References:
~~~~~~~~~~~
- `core/typedefs.h <https://github.com/godotengine/godot/blob/master/core/typedefs.h>`__
Memory model
------------
PC is a wonderful architecture. Computers often have gigabytes of RAM,
terabytes of storage and gigahertz of CPU, and when an application needs
more resources the OS will just swap out the inactive ones. Other
architectures (like mobile or consoles) are in general more limited.
The most common memory model is the heap, where an application will
request a region of memory, and the underlying OS will try to fit it
somewhere and return it. This often works best and is very flexible,
but over time and with abuse, this can lead to segmentation.
Segmentation slowly creates holes that are too small for most common
allocations, so that memory is wasted. There is a lot of literature
about heap and segmentation, so this topic will not be developed
further here. Modern operating systems use paged memory, which helps
mitigate the problem of segmentation but doesn't solve it.
However, in many studies and tests, it is shown that given enough
memory, if the maximum allocation size is below a given threshold in
proportion to the maximum heap size and proportion of memory intended to
be unused, segmentation will not be a problem over time as it will
remain constant. In other words, just leave 10-20% of your memory free
and perform all small allocations and you are fine.
Godot ensures that all objects that can be allocated dynamically are
small (less than a few kb at most). But what happens if an allocation is
too large (like an image or mesh geometry or large array)? In this case
Godot has the option to use a dynamic memory pool. This memory needs to
be locked to be accessed, and if an allocation runs out of memory, the
pool will be rearranged and compacted on demand. Depending on the need
of the game, the programmer can configure the dynamic memory pool size.
Allocating memory
-----------------
Godot has many tools for tracking memory usage in a game, specially
during debug. Because of this, the regular C and C++ library calls
should not be used. Instead, a few other ones are provided.
For C-style allocation, Godot provides a few macros:
.. code:: cpp
memalloc()
memrealloc()
memfree()
These are equivalent to the usual malloc, realloc, free of the standard
library.
For C++-style allocation, special macros are provided:
.. code:: cpp
memnew( Class / Class(args) )
memdelete( instance )
memnew_arr( Class , amount )
memdelete_arr( pointer to array )
which are equivalent to new, delete, new[] and delete[].
memnew/memdelete also use a little C++ magic and notify Objects right
after they are created, and right before they are deleted.
For dynamic memory, the DVector<> template is provided. Just use it
like:
.. code:: cpp
DVector<int>
DVector is just a standard vector class, it can be accessed using the []
operator, but that's probably slow for large amount of accesses (as it
has to lock internally). A few helpers exist for this:
.. code:: cpp
DVector<int>::Read r = dvector.read()
int someint = r[4]
and
.. code:: cpp
DVector<int>::Write w = dvector.write()
w[4]=22;
respectively. These allow fast read/write from DVectors and keep it
locked until they go out of scope.
References:
~~~~~~~~~~~
- `core/os/memory.h <https://github.com/godotengine/godot/blob/master/core/os/memory.h>`__
- `core/dvector.h <https://github.com/godotengine/godot/blob/master/core/dvector.h>`__
Containers
----------
Godot provides also a set of common containers:
- Vector
- List
- Set
- Map
They are very simple and aim to be as minimal as possible, as templates
in C++ are often inlined and make the binary size much fatter, both in
debug symbols and code. List, Set and Map can be iterated using
pointers, like this:
.. code:: cpp
for(List<int>::Element *E=somelist.front();E;E=E->next()) {
print_line(E->get()); //print the element
}
The Vector<> class also has a few nice features:
- It does copy on write, so making copies of it is cheap as long as
they are not modified.
- It supports multi-threading, by using atomic operations on the
reference counter.
References:
~~~~~~~~~~~
- `core/vector.h <https://github.com/godotengine/godot/blob/master/core/vector.h>`__
- `core/list.h <https://github.com/godotengine/godot/blob/master/core/list.h>`__
- `core/set.h <https://github.com/godotengine/godot/blob/master/core/set.h>`__
- `core/map.h <https://github.com/godotengine/godot/blob/master/core/map.h>`__
String
------
Godot also provides a String class. This class has a huge amount of
features, full Unicode support in all the functions (like case
operations) and utf8 parsing/extracting, as well as helpers for
conversion and visualization.
References:
~~~~~~~~~~~
- `core/ustring.h <https://github.com/godotengine/godot/blob/master/core/ustring.h>`__
StringName
----------
StringNames are like a String, but they are unique. Creating a
StringName from a string results in a unique internal pointer for all
equal strings. StringNames are really useful for using strings as
identifier, as comparing them is basically comparing a pointer.
Creation of a StringName (specially a new one) is slow, but comparison
is fast.
References:
~~~~~~~~~~~
- `core/string_db.h <https://github.com/godotengine/godot/blob/master/core/string_db.h>`__
Math types
----------
There are several linear math types available in the core/math
directory, they are basically just that.
References:
~~~~~~~~~~~
- `core/math <https://github.com/godotengine/godot/blob/master/core/math>`__
NodePath
--------
This is a special datatype used for storing paths in a scene tree and
referencing them fast.
References:
~~~~~~~~~~~
- `core/path_db.h <https://github.com/godotengine/godot/blob/master/core/path_db.h>`__
RID
---
RIDs are resource IDs. Servers use these to reference data stored in
them. RIDs are opaque, meaning that the data they reference can't be
accessed directly. RIDs are unique, even for different types of
referenced data.
References:
~~~~~~~~~~~
- `core/rid.h <https://github.com/godotengine/godot/blob/master/core/rid.h>`__

397
development/cpp/creating_android_modules.rst Normal file
View File

@@ -0,0 +1,397 @@
.. _doc_creating_android_modules:
Creating Android modules
========================
Introduction
------------
Making video games portable is all fine and dandy, until mobile
gaming monetization shows up.
This area is complex, usually a mobile game that monetizes needs
special connections to a server for stuff such as:
- Analytics
- In-app purchases
- Receipt validation
- Install tracking
- Ads
- Video ads
- Cross-promotion
- In-game soft & hard currencies
- Promo codes
- A/B testing
- Login
- Cloud saves
- Leaderboards and scores
- User support & feedback
- Posting to Facebook, Twitter, etc.
- Push notifications
Oh yeah, developing for mobile is a lot of work. On iOS, you can just
write a C++ module and take advantage of the C++/ObjC
intercommunication, so this is rather easy.
For C++ developers Java is a pain, the build system is severely bloated
and interfacing it with C++ through JNI (Java Native Interface) is more
pain that you don't want even for your worst enemy.
Maybe REST?
-----------
Most of these APIs allow communication via REST+JSON APIs. Godot has
great support for HTTP, HTTPS and JSON, so consider this as an option
that works in every platform. Only write the code once and you are set
to go.
Popular engines that have half the share of apps published on mobile get
special plugins written just for them. Godot does not have that luxury
yet. So, if you write a REST implementation of a SDK for Godot, please
share it with the community.
Android module
--------------
Writing an Android module is similar to :ref:`doc_custom_modules_in_c++`, but
needs a few more steps.
Make sure you are familiar with building your own :ref:`Android export templates <doc_compiling_for_android>`,
as well as creating :ref:`doc_custom_modules_in_c++`.
config.py
~~~~~~~~~
In the config.py for the module, some extra functions are provided for
convenience. First, it's often wise to detect if android is being built
and only enable building in this case:
.. code:: python
def can_build(plat):
return plat=="android"
If more than one platform can be built (typical if implementing the
module also for iOS), check manually for Android in the configure
functions:
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# android specific code
Java singleton
--------------
An android module will usually have a singleton class that will load it,
this class inherits from ``Godot.SingletonBase``. Resource identifiers for
any additional resources you have provided for the module will be in the
``com.godot.game.R`` class, so you'll likely want to import it.
A singleton object template follows:
.. code:: java
// package com.android.godot; // for 1.1
package org.godotengine.godot; // for 2.0
import com.godot.game.R;
public class MySingleton extends Godot.SingletonBase {
public int myFunction(String p_str) {
// a function to bind
}
static public Godot.SingletonBase initialize(Activity p_activity) {
return new MySingleton(p_activity);
}
public MySingleton(Activity p_activity) {
//register class name and functions to bind
registerClass("MySingleton", new String[]{"myFunction"});
// you might want to try initializing your singleton here, but android
// threads are weird and this runs in another thread, so you usually have to do
activity.runOnUiThread(new Runnable() {
public void run() {
//useful way to get config info from engine.cfg
String key = GodotLib.getGlobal("plugin/api_key");
SDK.initializeHere();
}
});
}
// forwarded callbacks you can reimplement, as SDKs often need them
protected void onMainActivityResult(int requestCode, int resultCode, Intent data) {}
protected void onMainPause() {}
protected void onMainResume() {}
protected void onMainDestroy() {}
protected void onGLDrawFrame(GL10 gl) {}
protected void onGLSurfaceChanged(GL10 gl, int width, int height) {} // singletons will always miss first onGLSurfaceChanged call
}
Calling back to Godot from Java is a little more difficult. The instance
ID of the script must be known first, this is obtained by calling
``get_instance_ID()`` on the script. This returns an integer that can be
passed to Java.
From Java, use the ``calldeferred`` function to communicate back with Godot.
Java will most likely run in a separate thread, so calls are deferred:
.. code:: java
GodotLib.calldeferred(<instanceid>, "<function>", new Object[]{param1,param2,etc});
Add this singleton to the build of the project by adding the following
to config.py:
(Before Version 2.0)
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# will copy this to the java folder
env.android_module_file("MySingleton.java")
#env.android_module_file("MySingleton2.java") call again for more files
(After Version 2.0)
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# will copy this to the java folder
env.android_add_java_dir("Directory that contain MySingleton.java")
AndroidManifest
---------------
Some SDKs need custom values in AndroidManifest.xml. Permissions can be
edited from the godot exporter so there is no need to add those, but
maybe other functionalities are needed.
Create the custom chunk of android manifest and put it inside the
module, add it like this:
(Before Version 2.0)
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# will copy this to the java folder
env.android_module_file("MySingleton.java")
env.android_module_manifest("AndroidManifestChunk.xml")
(After Version 2.0)
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# will copy this to the java folder
env.android_add_java_dir("Directory that contain MySingelton.java")
env.android_add_to_manifest("AndroidManifestChunk.xml")
Resources
---------
In order to provide additional resources with your module you have to
add something like this:
.. code:: python
def configure(env):
if env['platform'] == 'android':
# [...]
env.android_add_res_dir("Directory that contains resource subdirectories (values, drawable, etc.)")
Now you can refer to those resources by their id (``R.string.my_string``, and the like)
by importing the ``com.godot.game.R`` class in your Java code.
SDK library
-----------
So, finally it's time to add the SDK library. The library can come in
two flavors, a JAR file or an Android project for ant. JAR is the
easiest to integrate, just put it in the module directory and add it:
(Before Version 2.0)
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# will copy this to the java folder
env.android_module_file("MySingleton.java")
env.android_module_manifest("AndroidManifestChunk.xml")
env.android_module_library("MyLibrary-3.1.jar")
(After Version 2.0)
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# will copy this to the java folder
env.android_add_java_dir("Directory that contain MySingelton.java")
env.android_add_to_manifest("AndroidManifestChunk.xml")
env.android_add_dependency("compile files('something_local.jar')") # if you have a jar, the path is relative to platform/android/java/gradlew, so it will start with ../../../modules/module_name/
env.android_add_maven_repository("maven url") #add a maven url
env.android_add_dependency("compile 'com.google.android.gms:play-services-ads:8'") #get dependency from maven repository
SDK project
-----------
When this is an Android project, things usually get more complex. Copy
the project folder inside the module directory and configure it:
::
c:\godot\modules\mymodule\sdk-1.2> android -p . -t 15
As of this writing, Godot uses minsdk 10 and target sdk 15. If this ever
changes, it should be reflected in the manifest template:
`AndroidManifest.xml.template <https://github.com/godotengine/godot/blob/master/platform/android/AndroidManifest.xml.template>`
Then, add the module folder to the project:
(Before Version 2.0)
.. code:: python
def can_build(plat):
return plat=="android" or plat=="iphone"
def configure(env):
if env['platform'] == 'android':
# will copy this to the java folder
env.android_module_file("MySingleton.java")
env.android_module_manifest("AndroidManifestChunk.xml")
env.android_module_source("sdk-1.2","")
(After Version 2.0)
Building
--------
As you probably modify the contents of the module, and modify your .java
inside the module, you need the module to be built with the rest of
Godot, so compile android normally.
::
c:\godot> scons p=android
This will cause your module to be included, the .jar will be copied to
the java folder, the .java will be copied to the sources folder, etc.
Each time you modify the .java, scons must be called.
Afterwards, just continue the steps for compiling android :ref:`doc_compiling_for_android`.
Using the module
~~~~~~~~~~~~~~~~
To use the module from GDScript, first enable the singleton by adding
the following line to engine.cfg (Godot Engine 2.0 and greater):
::
[android]
modules="org/godotengine/godot/MySingleton"
For Godot Engine 1.1 is
::
[android]
modules="com/android/godot/MySingleton"
More than one singleton module can be enabled by separating with commas:
::
[android]
modules="com/android/godot/MySingleton,com/android/godot/MyOtherSingleton"
Then just request the singleton Java object from Globals like this:
::
# in any file
var singleton = null
func _init():
singleton = Globals.get_singleton("MySingleton")
print(singleton.myFunction("Hello"))
Troubleshooting
---------------
(This section is a work in progress, report your problems here!)
Godot crashes upon load
~~~~~~~~~~~~~~~~~~~~~~~
Check ``adb logcat`` for possible problems, then:
- Make sure libgodot_android.so is in the ``libs/armeabi`` folder
- Check that the methods used in the Java singleton only use simple
Java datatypes, more complex ones are not supported.
Future
------
Godot has an experimental Java API Wrapper that allows to use the
entire Java API from GDScript.
It's simple to use and it's used like this:
::
class = JavaClassWrapper.wrap(<javaclass as text>)
This is most likely not functional yet, if you want to test it and help
us make it work, contact us through the `developer mailing
list <https://groups.google.com/forum/#!forum/godot-engine>`__.

343
development/cpp/custom_modules_in_cpp.rst Normal file
View File

@@ -0,0 +1,343 @@
.. _doc_custom_modules_in_c++:
Custom modules in C++
=====================
Modules
-------
Godot allows extending the engine in a modular way. New modules can be
created and then enabled/disabled. This allows for adding new engine
functionality at every level without modifying the core, which can be
split for use and reuse in different modules.
Modules are located in the ``modules/`` subdirectory of the build system.
By default, two modules exist, GDScript (which, yes, is not part of the
core engine), and the GridMap. As many new modules as desired can be
created and combined, and the SCons build system will take care of it
transparently.
What for?
---------
While it's recommended that most of a game is written in scripting (as
it is an enormous time saver), it's perfectly possible to use C++
instead. Adding C++ modules can be useful in the following scenarios:
- Binding an external library to Godot (like Bullet, Physx, FMOD, etc).
- Optimize critical parts of a game.
- Adding new functionality to the engine and/or editor.
- Porting an existing game.
- Write a whole, new game in C++ because you can't live without C++.
Creating a new module
---------------------
Before creating a module, make sure to download the source code of Godot
and manage to compile it. There are tutorials in the documentation for this.
To create a new module, the first step is creating a directory inside
``modules/``. If you want to maintain the module separately, you can checkout
a different VCS into modules and use it.
The example module will be called "sumator", and is placed inside the
Godot source tree (``C:\godot`` refers to wherever the Godot sources are
located):
::
C:\godot> cd modules
C:\godot\modules> mkdir sumator
C:\godot\modules> cd sumator
C:\godot\modules\sumator>
Inside we will create a simple sumator class:
.. code:: cpp
/* sumator.h */
#ifndef SUMATOR_H
#define SUMATOR_H
#include "reference.h"
class Sumator : public Reference {
OBJ_TYPE(Sumator,Reference);
int count;
protected:
static void _bind_methods();
public:
void add(int value);
void reset();
int get_total() const;
Sumator();
};
#endif
And then the cpp file.
.. code:: cpp
/* sumator.cpp */
#include "sumator.h"
void Sumator::add(int value) {
count+=value;
}
void Sumator::reset() {
count=0;
}
int Sumator::get_total() const {
return count;
}
void Sumator::_bind_methods() {
ObjectTypeDB::bind_method("add",&Sumator::add);
ObjectTypeDB::bind_method("reset",&Sumator::reset);
ObjectTypeDB::bind_method("get_total",&Sumator::get_total);
}
Sumator::Sumator() {
count=0;
}
Then, the new class needs to be registered somehow, so two more files
need to be created:
::
register_types.h
register_types.cpp
With the following contents:
.. code:: cpp
/* register_types.h */
void register_sumator_types();
void unregister_sumator_types();
/* yes, the word in the middle must be the same as the module folder name */
.. code:: cpp
/* register_types.cpp */
#include "register_types.h"
#include "object_type_db.h"
#include "sumator.h"
void register_sumator_types() {
ObjectTypeDB::register_type<Sumator>();
}
void unregister_sumator_types() {
//nothing to do here
}
Next, we need to create a ``SCsub`` file so the build system compiles
this module:
.. code:: python
# SCsub
Import('env')
env.add_source_files(env.modules_sources,"*.cpp") # just add all cpp files to the build
If you want to add custom compiler flags when building your module, you need to clone
`env` first, so it won't add those flags to whole Godot build (which can cause errors).
Example `SCsub` with custom flags:
.. code:: python
# SCsub
Import('env')
module_env = env.Clone()
module_env.add_source_files(env.modules_sources,"*.cpp")
module_env.Append(CXXFLAGS=['-O2', '-std=c++11'])
And finally, the configuration file for the module, this is a simple
python script that must be named ``config.py``:
.. code:: python
# config.py
def can_build(platform):
return True
def configure(env):
pass
The module is asked if it's ok to build for the specific platform (in
this case, True means it will build for every platform).
And that's it. Hope it was not too complex! Your module should look like
this:
::
godot/modules/sumator/config.py
godot/modules/sumator/sumator.h
godot/modules/sumator/sumator.cpp
godot/modules/sumator/register_types.h
godot/modules/sumator/register_types.cpp
godot/modules/sumator/SCsub
You can then zip it and share the module with everyone else. When
building for every platform (instructions in the previous sections),
your module will be included.
Using the module
----------------
Using your newly created module is very easy, from any script you can
now do:
::
var s = Sumator.new()
s.add(10)
s.add(20)
s.add(30)
print(s.get_total())
s.reset()
And the output will be ``60``.
Improving the build system for development
------------------------------------------
So far we defined a clean and simple SCsub that allows us to add the sources
of our new module as part of the Godot binary.
This static approach is fine when we want to build a release version of our
game given we want all the modules in a single binary.
However the trade-of is every single change means a full recompilation of the
game. Even if SCons is able to detect and recompile only the file that have
changed, finding such files and eventually linking the final binary is a
long and costly part.
The solution to avoid such a cost is to build our own module as a shared
library that will be dynamically loaded when starting our game's binary.
.. code:: python
# SCsub
Import('env')
sources = [
"register_types.cpp",
"sumator.cpp"
]
# First, create a custom env for the shared library.
module_env = env.Clone()
module_env.Append(CXXFLAGS='-fPIC') # Needed to compile shared library
# We don't want godot's dependencies to be injected into our shared library.
module_env['LIBS'] = []
# Now define the shared library. Note that by default it would be built
# into the module's folder, however it's better to output it into `bin`
# next to the godot binary.
shared_lib = module_env.SharedLibrary(target='#bin/sumator', source=sources)
# Finally notify the main env it has our shared lirary as a new dependency.
# To do so, SCons wants the name of the lib with it custom suffixes
# (e.g. ".x11.tools.64") but without the final ".so".
# We pass this along with the directory of our library to the main env.
shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
env.Append(LIBS=[shared_lib_shim])
env.Append(LIBPATH=['#bin'])
Once compiled, we should end up with a ``bin`` directory containing both the
``godot*`` binary and our ``libsumator*.so``. However given the .so is not in
a standard directory (like ``/usr/lib``), we have to help our binary find it
during runtime with the ``LD_LIBRARY_PATH`` environ variable:
::
user@host:~/godot$ export LD_LIBRARY_PATH=`pwd`/bin/
user@host:~/godot$ ./bin/godot*
**note**: Pay attention you have to ``export`` the environ variable otherwise
you won't be able to play you project from within the editor.
On top of that, it would be nice to be able to select whether to compile our
module as shared library (for development) or as a part of the godot binary
(for release). To do that we can define a custom flag to be passed to SCons
using the `ARGUMENT` command:
.. code:: python
# SCsub
Import('env')
sources = [
"register_types.cpp",
"sumator.cpp"
]
module_env = env.Clone()
module_env.Append(CXXFLAGS=['-O2', '-std=c++11'])
if ARGUMENTS.get('sumator_shared', 'no') == 'yes':
# Shared lib compilation
module_env.Append(CXXFLAGS='-fPIC')
module_env['LIBS'] = []
shared_lib = module_env.SharedLibrary(target='#bin/sumator', source=sources)
shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
env.Append(LIBS=[shared_lib_shim])
env.Append(LIBPATH=['#bin'])
else:
# Static compilation
module_env.add_source_files(env.modules_sources, sources)
Now by default ``scons`` command will build our module as part of godot's binary
and as a shared library when passing ``sumator_shared=yes``.
Finally you can even speedup build further by explicitly specifying your
shared module as target in the scons command:
::
user@host:~/godot$ scons sumator_shared=yes bin/sumator.x11.tools.64.so
Summing up
----------
As you see, it's really easy to develop Godot in C++. Just write your
stuff normally and remember to:
- use ``OBJ_TYPE`` macro for inheritance, so Godot can wrap it
- use ``_bind_methods`` to bind your functions to scripting, and to
allow them to work as callbacks for signals.
But this is not all, depending what you do, you will be greeted with
some surprises.
- If you inherit from :ref:`class_Node` (or any derived node type, such as
Sprite), your new class will appear in the editor, in the inheritance
tree in the "Add Node" dialog.
- If you inherit from :ref:`class_Resource`, it will appear in the resource
list, and all the exposed properties can be serialized when
saved/loaded.
- By this same logic, you can extend the Editor and almost any area of
the engine.

29
development/cpp/inheritance_class_tree.rst Normal file
View File

@@ -0,0 +1,29 @@
Inheritance class tree
======================
Object
------
.. image:: /img/Object.png
Reference
---------
.. image:: /img/Reference.png
Control
-------
.. image:: /img/Control.png
Node2D
------
.. image:: /img/Node2D.png
Spatial
-------
.. image:: /img/Spatial.png
Source files: :download:`class_tree.zip </files/class_tree.zip>`.

40
development/cpp/introduction_to_godot_development.rst Normal file
View File

@@ -0,0 +1,40 @@
.. _doc_introduction_to_godot_development:
Introduction to Godot development
=================================
This page is meant to introduce the global organization of Godot Engine's
source code, and give useful tips for extending/fixing the engine on the
C++ side.
Architecture diagram
--------------------
The following diagram describes the architecture used by Godot, from the
core components down to the abstracted drivers, via the scene
structure and the servers.
.. image:: /img/architecture_diagram.jpg
Debugging the editor with gdb
-----------------------------
If you are writing or correcting bugs affecting Godot Engine's editor,
remember that the binary will by default run the project manager first,
and then only run the editor in another process once you've selected a
project. To launch a project directly, you need to run the editor by
passing the ``-e`` argument to Godot Engine's binary from within your
project's folder. Typically:
.. code:: bash
$ cd ~/myproject
$ gdb godot
> run -e
Or:
.. code:: bash
$ gdb godot
> run -e -path ~/myproject

310
development/cpp/object_class.rst Normal file
View File

@@ -0,0 +1,310 @@
.. _doc_object_class:
Object class
============
General definition
------------------
:ref:`Object <class_object>` is the base class for almost everything. Most classes in Godot
inherit directly or indirectly from it. Objects provide reflection and
editable properties, and declaring them is a matter of using a single
macro like this.
.. code:: cpp
class CustomObject : public Object {
OBJ_TYPE(CustomObject,Object); // this is required to inherit
};
This makes Objects gain a lot of functionality, like for example
.. code:: cpp
obj = memnew(CustomObject);
print_line("Object Type: ",obj->get_type()); //print object type
obj2 = obj->cast_to<OtherType>(); // converting between types, this also works without RTTI enabled.
References:
~~~~~~~~~~~
- `core/object.h <https://github.com/godotengine/godot/blob/master/core/object.h>`__
Registering an Object
---------------------
ObjectTypeDB is a static class that holds the entire list of registered
classes that inherit from Object, as well as dynamic bindings to all
their methods properties and integer constants.
Classes are registered by calling:
.. code:: cpp
ObjectTypeDB::register_type<MyCustomType>()
Registering it will allow the type to be instanced by scripts, code, or
creating them again when deserializing.
Registering as virtual is the same but it can't be instanced.
.. code:: cpp
ObjectTypeDB::register_virtual_type<MyCustomType>()
Object-derived classes can override the static function
``static void _bind_methods()``. When one class is registered, this
static function is called to register all the object methods,
properties, constants, etc. It's only called once. If an Object derived
class is instanced but has not been registered, it will be registered as
virtual automatically.
Inside ``_bind_methods``, there are a couple of things that can be done.
Registering functions is one:
.. code:: cpp
ObjectTypeDB::register_method(_MD("methodname","arg1name","arg2name"),&MyCustomMethod);
Default values for arguments can be passed in reverse order:
.. code:: cpp
ObjectTypeDB::register_method(_MD("methodname","arg1name","arg2name"),&MyCustomType::method,DEFVAL(-1)); //default value for arg2name
``_MD`` is a macro that converts "methodname" to a StringName for more
efficiency. Argument names are used for introspection, but when
compiling on release, the macro ignores them, so the strings are unused
and optimized away.
Check ``_bind_methods`` of Control or Object for more examples.
If just adding modules and functionality that is not expected to be
documented as thoroughly, the ``_MD()`` macro can safely be ignored and a
string passing the name can be passed for brevity.
References:
~~~~~~~~~~~
- `core/object_type_db.h <https://github.com/godotengine/godot/blob/master/core/object_type_db.h>`__
Constants
---------
Classes often have enums such as:
.. code:: cpp
enum SomeMode {
MODE_FIRST,
MODE_SECOND
};
For these to work when binding to methods, the enum must be declared
convertible to int, for this a macro is provided:
.. code:: cpp
VARIANT_ENUM_CAST( MyClass::SomeMode ); // now functions that take SomeMode can be bound.
The constants can also be bound inside ``_bind_methods``, by using:
.. code:: cpp
BIND_CONSTANT( MODE_FIRST );
BIND_CONSTANT( MODE_SECOND );
Properties (set/get)
--------------------
Objects export properties, properties are useful for the following:
- Serializing and deserializing the object.
- Creating a list of editable values for the Object derived class.
Properties are usually defined by the PropertyInfo() class. Usually
constructed as:
.. code:: cpp
PropertyInfo(type,name,hint,hint_string,usage_flags)
For example:
.. code:: cpp
PropertyInfo(Variant::INT,"amount",PROPERTY_HINT_RANGE,"0,49,1",PROPERTY_USAGE_EDITOR)
This is an integer property, named "amount", hint is a range, range goes
from 0 to 49 in steps of 1 (integers). It is only usable for the editor
(edit value visually) but won't be serialized.
Another example:
.. code:: cpp
PropertyInfo(Variant::STRING,"modes",PROPERTY_HINT_ENUM,"Enabled,Disabled,Turbo")
This is a string property, can take any string but the editor will only
allow the defined hint ones. Since no usage flags were specified, the
default ones are PROPERTY_USAGE_STORAGE and PROPERTY_USAGE_EDITOR.
There are plenty of hints and usage flags available in object.h, give them a
check.
Properties can also work like C# properties and be accessed from script
using indexing, but this usage is generally discouraged, as using
functions is preferred for legibility. Many properties are also bound
with categories, such as "animation/frame" which also make indexing
impossible unless using operator [].
From ``_bind_methods()``, properties can be created and bound as long as
set/get functions exist. Example:
.. code:: cpp
ADD_PROPERTY( PropertyInfo(Variant::INT,"amount"), _SCS("set_amount"), _SCS("get_amount") )
This creates the property using the setter and the getter. ``_SCS`` is a
macro that creates a StringName efficiently.
Binding properties using ``_set``/``_get``/``_get_property_list``
-----------------------------------------------------------------
An additional method of creating properties exists when more flexibility
is desired (i.e. adding or removing properties on context).
The following functions can be overridden in an Object derived class,
they are NOT virtual, DO NOT make them virtual, they are called for
every override and the previous ones are not invalidated (multilevel
call).
.. code:: cpp
void _get_property_info(List<PropertyInfo> *r_props); //return list of properties
bool _get(const StringName& p_property, Variany& r_value) const; //return true if property was found
bool _set(const StringName& p_property, const Variany& p_value); //return true if property was found
This is also a little less efficient since ``p_property`` must be
compared against the desired names in serial order.
Dynamic casting
---------------
Godot provides dynamic casting between Object-derived classes, for
example:
.. code:: cpp
void somefunc(Object *some_obj) {
Button *button = some_obj->cast_to<Button>();
}
If cast fails, NULL is returned. This system uses RTTI, but it also
works fine (although a bit slower) when RTTI is disabled. This is useful
on platforms where a very small binary size is ideal, such as HTML5 or
consoles (with low memory footprint).
Signals
-------
Objects can have a set of signals defined (similar to Delegates in other
languages). Connecting to them is rather easy:
.. code:: cpp
obj->connect(<signal>,target_instance,target_method)
//for example
obj->connect("enter_tree",this,"_node_entered_tree")
The method ``_node_entered_tree`` must be registered to the class using
``ObjectTypeDB::register_method`` (explained before).
Adding signals to a class is done in ``_bind_methods``, using the
``ADD_SIGNAL`` macro, for example:
.. code:: cpp
ADD_SIGNAL( MethodInfo("been_killed") )
References
----------
:ref:`Reference <class_reference>` inherits from Object and holds a
reference count. It is the base for reference counted object types.
Declaring them must be done using Ref<> template. For example:
.. code:: cpp
class MyReference: public Reference {
OBJ_TYPE( MyReference,Reference );
};
Ref<MyReference> myref = memnew( MyReference );
``myref`` is reference counted. It will be freed when no more Ref<>
templates point to it.
References:
~~~~~~~~~~~
- `core/reference.h <https://github.com/godotengine/godot/blob/master/core/reference.h>`__
Resources:
----------
:ref:`Resource <class_resource>` inherits from Reference, so all resources
are reference counted. Resources can optionally contain a path, which
reference a file on disk. This can be set with ``resource.set_path(path)``.
This is normally done by the resource loader though. No two different
resources can have the same path, attempt to do so will result in an error.
Resources without a path are fine too.
References:
~~~~~~~~~~~
- `core/resource.h <https://github.com/godotengine/godot/blob/master/core/resource.h>`__
Resource loading
----------------
Resources can be loaded with the ResourceLoader API, like this:
.. code:: cpp
Ref<Resource> res = ResourceLoader::load("res://someresource.res")
If a reference to that resource has been loaded previously and is in
memory, the resource loader will return that reference. This means that
there can be only one resource loaded from a file referenced on disk at
the same time.
- resourceinteractiveloader (TODO)
References:
~~~~~~~~~~~
- `core/io/resource_loader.h <https://github.com/godotengine/godot/blob/master/core/io/resource_loader.h>`__
Resource saving
---------------
Saving a resource can be done with the resource saver API:
.. code:: cpp
ResourceSaver::save("res://someresource.res",instance)
Instance will be saved. Sub resources that have a path to a file will be
saved as a reference to that resource. Sub resources without a path will
be bundled with the saved resource and assigned sub-IDs, like
"res://someresource.res::1". This also helps to cache them when loaded.
References:
~~~~~~~~~~~
- `core/io/resource_saver.h <https://github.com/godotengine/godot/blob/master/core/io/resource_saver.h>`__

62
development/cpp/variant_class.rst Normal file
View File

@@ -0,0 +1,62 @@
.. _doc_variant_class:
Variant class
=============
About
-----
Variant is the most important datatype of Godot, it's the most important
class in the engine. A Variant takes up only 20 bytes and can store
almost any engine datatype inside of it. Variants are rarely used to
hold information for long periods of time, instead they are used mainly
for communication, editing, serialization and generally moving data
around.
A Variant can:
- Store almost any datatype
- Perform operations between many variants (GDScript uses Variant as
its atomic/native datatype).
- Be hashed, so it can be compared quickly to over variants
- Be used to convert safely between datatypes
- Be used to abstract calling methods and their arguments (Godot
exports all its functions through variants)
- Be used to defer calls or move data between threads.
- Be serialized as binary and stored to disk, or transferred via
network.
- Be serialized to text and use it for printing values and editable
settings.
- Work as an exported property, so the editor can edit it universally.
- Be used for dictionaries, arrays, parsers, etc.
Basically, thanks to the Variant class, writing Godot itself was a much,
much easier task, as it allows for highly dynamic constructs not common
of C++ with little effort. Become a friend of Variant today.
References:
~~~~~~~~~~~
- `core/variant.h <https://github.com/godotengine/godot/blob/master/core/variant.h>`__
Dictionary and Array
--------------------
Both are implemented using variants. A Dictionary can match any datatype
used as key to any other datatype. An Array just holds an array of
Variants. Of course, a Variant can also hold a Dictionary and an Array
inside, making it even more flexible.
Both have a shared mode and a COW mode. Scripts often use them in shared
mode (meaning modifications to a container will modify all references to
it), or COW mode (modifications will always alter the local copy, making
a copy of the internal data if necessary, but will not affect the other
copies). In COW mode, Both Dictionary and Array are thread-safe,
otherwise a Mutex should be created to lock if multi thread access is
desired.
References:
~~~~~~~~~~~
- `core/dictionary.h <https://github.com/godotengine/godot/blob/master/core/dictionary.h>`__
- `core/array.h <https://github.com/godotengine/godot/blob/master/core/array.h>`__

254
development/plugins/making_plugins.rst Normal file
View File

@@ -0,0 +1,254 @@
.. _doc_making_plugins:
Making Plugins
==============
.. Remove this warning when 2.1 is release
*Important:* This tutorial applies only to the upcoming version 2.1.
About Plugins
~~~~~~~~~~~~~
A plugin is a great way to extend the editor with useful tools. It can be made
entirely with GDScript and standard scenes, without even reloading the editor.
Unlike modules, you don't need to create C++ code nor recompile the engine.
While this makes plugins not as powerful, there's still a lot of things you can
do with them. Note that a plugin is not different from any scene you already
can make, except that it is made via script to add functionality.
This tutorial will guide you through the creation of two simple plugins so
you can understand how they work and be able to develop your own. The first
will be a custom node that you can add to any scene in the project and the
other will be a custom dock added to the editor.
Creating a plugin
~~~~~~~~~~~~~~~~~
Before starting, create a new empty project wherever you want. This will serve
as base to develop and test the plugins.
The first thing you need to do is to create a new plugin that the editor can
understand as such. For that you need two files: ``plugin.cfg`` for the
configuration and a custom GDScript with the functionality.
Plugins have a standard path like ``addons/plugin_name`` inside the project
folder. So create the folder ``my_custom_node`` inside ``addons``. So you'll
have a directory structure like this:
.. image:: /img/making_plugins-my_custom_mode_folder.png
To make the ``plugin.cfg`` file, open your favorite text editor with a blank
file. Godot is not able (yet) to open text files besides scripts, so this must
be done in an external editor. Add the following structure to your
``plugin.cfg``::
[plugin]
name="My Custom Node"
description="A custom node made to extend the Godot Engine."
author="Your Name Here"
version="1.0"
script="custom_node.gd"
This is a simple ``ini`` file with metadata about your plugin. You need to set
up the name and description so users can understand what it does. Add your
own name so you can be properly credited. A version number is useful so users can see if
they have an outdated version (if you are unsure on how to come up with
the version number, check `SemVer <http://semver.org/>`_). And finally a main
script file to load when your plugin is active.
The script file
^^^^^^^^^^^^^^^
Open the script editor (F3) and create a new GDScript file called
``custom_node.gd`` inside the ``my_custom_node`` folder. This script is special
and it has two requirements: it must be a ``tool`` script and it has to
inherit from :ref:`class_EditorPlugin`.
It's important to deal with initialization and clean-up of resources. So a good
practice is to use the virtual function
:ref:`_enter_tree() <class_Node__enter_tree>` to initialize your plugin and
:ref:`_exit_tree() <class_Node__exit_tree>` to clean it up. You can delete the
default GDScript template from your file and replace it with the following
structure:
.. _doc_making_plugins_template_code:
.. code-block:: python
tool
extends EditorPlugin
func _enter_tree():
# Initialization of the plugin goes here
pass
func _exit_tree():
# Clean-up of the plugin goes here
pass
This is a good template to use when devising new plugins.
A custom node
~~~~~~~~~~~~~~~~~~~~
Sometimes you want a certain behavior in many nodes. Maybe a custom scene
or control that can be reused. Instancing is helpful in a lot of cases but
sometimes it can be cumbersome, especially if you're using it between many
projects. A good solution to this is to make a plugin that adds a node with a
custom behavior.
To create a new node type, you can avail of the function
:ref:`add_custom_type() <class_EditorPlugin_add_custom_type>` from the
:ref:`class_EditorPlugin` class. This function can add new types to the editor,
be it nodes or resources. But before you can create the type you need a script
that will act as the logic for the type. While such script doesn't need to have
the ``tool`` keyword, it is interesting to use it so the user can see it acting
on the editor.
For this tutorial, we'll create a simple button that prints a message when
clicked. And for that we'll need a simple script that extends from
:ref:`class_Button`. It could also extend
:ref:`class_BaseButton` if you prefer::
tool
extends Button
func _enter_tree():
connect("pressed", self, "clicked")
func clicked():
print("You clicked me!")
That's it for our basic button. You can save this as ``button.gd`` inside the
plugin folder. You'll also need a 16x16 icon to show in the scene tree. If you
don't have one, you can grab the default one from the engine:
.. image:: /img/making_plugins-custom_node_icon.png
Now we need to add it as a custom type so it shows on the Create New Node
dialog. For that, change the ``custom_node.gd`` script to the following::
tool
extends EditorPlugin
func _enter_tree():
# Initialization of the plugin goes here
# Add the new type with a name, a parent type, a script and an icon
add_custom_type("MyButton", "Button", preload("button.gd"), preload("icon.png"))
func _exit_tree():
# Clean-up of the plugin goes here
# Always remember to remove it from the engine when deactivated
remove_custom_type("MyButton")
With that done, the plugin should already be available in the plugin list at
Project Settings. So activate it and try to add a new node to see the result:
.. image:: /img/making_plugins-custom_node_create.png
When you add the node, you can see that it already have the script you created
attached to it. Set a text to the button, save and run the scene. When you
click the button, you can see a text in the console:
.. image:: /img/making_plugins-custom_node_console.png
A custom dock
^^^^^^^^^^^^^
Maybe you need to extend the editor and add tools that are always available.
An easy way to do it is to add a new dock with a plugin. Docks are just scenes
based on control, so how to create them is not far beyond your knowledge.
The way to start this plugin is similar to the custom node. So create a new
``plugin.cfg`` file in the ``addons/my_custom_dock`` folder. And then with
your favorite text editor add the following content to it::
[plugin]
name="My Custom Dock"
description="A custom dock made so I can learn how to make plugins."
author="Your Name Here"
version="1.0"
script="custom_dock.gd"
Then create the script ``custom_dock.gd`` in the same folder. Fill with the
:ref:`template we've seen before <doc_making_plugins_template_code>` to get a
good start.
Since we're trying to add a new custom dock, we need to create the contents of
such dock. This is nothing more than a standard Godot scene. So you can create
a new scene in the editor and start creating it.
For an editor dock, it is mandatory that the root of the scene is a
:ref:`Control <class_Control>` or one of its child classes. For this tutorial,
you can make a single button. The name of the root node will also be the name
that appears on the dock tab, so be sure to put a descriptive but short one.
Don't forget to add a text to your button.
.. image:: /img/making_plugins-my_custom_dock_scene.png
Save this scene as ``my_dock.tscn``.
Now you need to grab that scene you just created and add it as a dock in the
editor. For this you can rely on the function
:ref:`add_control_to_dock() <class_EditorPlugin_add_control_to_dock>` from the
:ref:`EditorPlugin <class_EditorPlugin>` class.
The code is very straightforward, you just need to select a dock position to
add it and have a control to add (which is the scene you just created). It is
also very important that you remember to **remove the dock** when the plugin is
deactivated. The code can be like this::
tool
extends EditorPlugin
var dock # A class member to hold the dock during the plugin lifecycle
func _enter_tree():
# Initialization of the plugin goes here
# First load the dock scene and instance it:
dock = preload("res://addons/my_custom_dock/my_dock.tscn").instance()
# Add the loaded scene to the docks:
add_control_to_dock( DOCK_SLOT_LEFT_UL, dock)
# Note that LEFT_UL means the left of the editor, upper-left dock
func _exit_tree():
# Clean-up of the plugin goes here
# Remove the scene from the docks:
remove_control_from_docks( dock ) # Remove the dock
dock.free() # Erase the control from the memory
While the dock position is chosen when adding it, the user is free to move it
and save the layout with the dock in any position.
Checking the results
^^^^^^^^^^^^^^^^^^^^
Now it is the moment to check the results of your work. Open the *Project
Settings* and click on the *Plugins* tab. Your plugin should be the only on
the list. If it is not showing, click on the *Update* button at the top right
corner.
.. image:: /img/making_plugins-project_settings.png
At the *Status* column, you can see that the plugin is inactive. So you just
need to click on the status to select *Active*. The dock should be immediately
visible, even before you close the settings window. And now, lo and behold, you
have a custom dock! In just a bit of coding and a simple scene.
.. image:: /img/making_plugins-custom_dock.png
Going beyond
~~~~~~~~~~~~
Now that you learned how to make basic plugins, you can extend the editor in
many nice ways. Many functions can be added to editor on the fly with GDScript,
it is a powerful way to create special editors without having to delve into C++
modules.
You can make your own plugins to help you and also share them in Godot's Asset
Library so many people can benefit of your work.