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

Import first batch of pages

Browse Source
This commit is contained in:
Rémi Verschelde
2015-12-12 17:57:44 +01:00
parent 33fe0bbde6
commit 86563cc374
43 changed files with 3995 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
_build/

17
Makefile
View File

@@ -19,7 +19,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@@ -30,6 +30,7 @@ help:
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@@ -45,6 +46,7 @@ help:
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
@@ -89,6 +91,14 @@ qthelp:
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GodotEngine.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@@ -166,6 +176,11 @@ doctest:
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# Godot Engine documentation
This repository contains the source files of Godot Engine's documentation.

171
advanced_topics/batch_building_templates.rst Normal file
View File

@@ -0,0 +1,171 @@
Batch building templates
========================
The following is almost the same exact script we use to build all the
export templates that go to the site. If you want to build or roll them
yourself, this might be of use.
(note: mac 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
ant -s platform/android/java/build.xml release
cp platform/android/java/bin/Godot-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
ant -s platform/android/java/build.xml release
cp platform/android/java/bin/Godot-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 ../../..

491
advanced_topics/binary_serialization_api.rst Normal file
View File

@@ -0,0 +1,491 @@
Binary serialization API
========================
Introduction
------------
Godot has a simple serialization API based on Variant. It's used for
converting data types to an array of bytes efficiently. This API is used
in the functions ``get_var`` and ``store_var`` of the [[API:File\|File
class]] as well as the packet APIs for [[API:PacketPeer]]. This format
is not used for binary scenes and resources.
Packet specification
--------------------
| The packet is designed to be always padded to 4 bytes. All values are
little endian encoded.
| All packets have a 4 byte header representing an integer, specifying
the type of data:
+--------+--------------------------+
| Type | Value |
+========+==========================+
| 0 | null |
+--------+--------------------------+
| 1 | bool |
+--------+--------------------------+
| 2 | integer |
+--------+--------------------------+
| 3 | float |
+--------+--------------------------+
| 4 | string |
+--------+--------------------------+
| 5 | vector2 |
+--------+--------------------------+
| 6 | rect2 |
+--------+--------------------------+
| 7 | vector3 |
+--------+--------------------------+
| 8 | matrix32 |
+--------+--------------------------+
| 9 | plane |
+--------+--------------------------+
| 10 | quaternion |
+--------+--------------------------+
| 11 | aabb (rect3) |
+--------+--------------------------+
| 12 | matrix3x3 |
+--------+--------------------------+
| 13 | transform (matrix 4x3) |
+--------+--------------------------+
| 14 | color |
+--------+--------------------------+
| 15 | image |
+--------+--------------------------+
| 16 | node path |
+--------+--------------------------+
| 17 | rid (unsupported) |
+--------+--------------------------+
| 18 | object (unsupported) |
+--------+--------------------------+
| 19 | input event |
+--------+--------------------------+
| 20 | dictionary |
+--------+--------------------------+
| 21 | array |
+--------+--------------------------+
| 22 | byte array |
+--------+--------------------------+
| 23 | int array |
+--------+--------------------------+
| 24 | float array |
+--------+--------------------------+
| 25 | string array |
+--------+--------------------------+
| 26 | vector2 array |
+--------+--------------------------+
| 27 | vector3 array |
+--------+--------------------------+
| 28 | color array |
+--------+--------------------------+
Following this is the actual packet contents, which varies for each type
of packet:
0: null
~~~~~~~
1: bool
~~~~~~~
+----------+-------+-----------+---------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+===========================+
| 4 | 4 | Integer | 0 for False, 1 for True |
+----------+-------+-----------+---------------------------+
2: integer
~~~~~~~~~~
+----------+-------+-----------+--------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+==========================+
| 4 | 4 | Integer | Signed, 32-Bit Integer |
+----------+-------+-----------+--------------------------+
3: float
~~~~~~~~
+----------+-------+---------+-------------------------+
| Offset | Len | Type | Description |
+==========+=======+=========+=========================+
| 4 | 4 | Float | IEE 754 32-Bits Float |
+----------+-------+---------+-------------------------+
4: string
~~~~~~~~~
+----------+-------+-----------+----------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+============================+
| 4 | 4 | Integer | String Length (in Bytes) |
+----------+-------+-----------+----------------------------+
| 8 | X | Bytes | UTF-8 Encoded String |
+----------+-------+-----------+----------------------------+
This field is padded to 4 bytes.
5: vector2
~~~~~~~~~~
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
+----------+-------+---------+----------------+
6: rect2
~~~~~~~~
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
+----------+-------+---------+----------------+
| 12 | 4 | Float | X Size |
+----------+-------+---------+----------------+
| 16 | 4 | Float | Y Size |
+----------+-------+---------+----------------+
7: vector3
~~~~~~~~~~
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
+----------+-------+---------+----------------+
| 12 | 4 | Float | Z Coordinate |
+----------+-------+---------+----------------+
8: matrix32
~~~~~~~~~~~
+----------+-------+---------+---------------+
| Offset | Len | Type | Description |
+==========+=======+=========+===============+
| 4 | 4 | Float | [0][0] |
+----------+-------+---------+---------------+
| 8 | 4 | Float | [0][1] |
+----------+-------+---------+---------------+
| 12 | 4 | Float | [1][0] |
+----------+-------+---------+---------------+
| 16 | 4 | Float | [1][1] |
+----------+-------+---------+---------------+
| 20 | 4 | Float | [2][0] |
+----------+-------+---------+---------------+
| 24 | 4 | Float | [2][1] |
+----------+-------+---------+---------------+
9: plane
~~~~~~~~
+----------+-------+---------+---------------+
| Offset | Len | Type | Description |
+==========+=======+=========+===============+
| 4 | 4 | Float | Normal X |
+----------+-------+---------+---------------+
| 8 | 4 | Float | Normal Y |
+----------+-------+---------+---------------+
| 12 | 4 | Float | Normal Z |
+----------+-------+---------+---------------+
| 16 | 4 | Float | Distance |
+----------+-------+---------+---------------+
10: quaternion
~~~~~~~~~~~~~~
+----------+-------+---------+---------------+
| Offset | Len | Type | Description |
+==========+=======+=========+===============+
| 4 | 4 | Float | Imaginary X |
+----------+-------+---------+---------------+
| 8 | 4 | Float | Imaginary Y |
+----------+-------+---------+---------------+
| 12 | 4 | Float | Imaginary Z |
+----------+-------+---------+---------------+
| 16 | 4 | Float | Real W |
+----------+-------+---------+---------------+
11: aabb (rect3)
~~~~~~~~~~~~~~~~
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
+----------+-------+---------+----------------+
| 12 | 4 | Float | Z Coordinate |
+----------+-------+---------+----------------+
| 16 | 4 | Float | X Size |
+----------+-------+---------+----------------+
| 20 | 4 | Float | Y Size |
+----------+-------+---------+----------------+
| 24 | 4 | Float | Z Size |
+----------+-------+---------+----------------+
12: matrix3x3
~~~~~~~~~~~~~
+----------+-------+---------+---------------+
| Offset | Len | Type | Description |
+==========+=======+=========+===============+
| 4 | 4 | Float | [0][0] |
+----------+-------+---------+---------------+
| 8 | 4 | Float | [0][1] |
+----------+-------+---------+---------------+
| 12 | 4 | Float | [0][2] |
+----------+-------+---------+---------------+
| 16 | 4 | Float | [1][0] |
+----------+-------+---------+---------------+
| 20 | 4 | Float | [1][1] |
+----------+-------+---------+---------------+
| 24 | 4 | Float | [1][2] |
+----------+-------+---------+---------------+
| 28 | 4 | Float | [2][0] |
+----------+-------+---------+---------------+
| 32 | 4 | Float | [2][1] |
+----------+-------+---------+---------------+
| 36 | 4 | Float | [2][2] |
+----------+-------+---------+---------------+
13: transform (matrix 4x3)
~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------+-------+---------+---------------+
| Offset | Len | Type | Description |
+==========+=======+=========+===============+
| 4 | 4 | Float | [0][0] |
+----------+-------+---------+---------------+
| 8 | 4 | Float | [0][1] |
+----------+-------+---------+---------------+
| 12 | 4 | Float | [0][2] |
+----------+-------+---------+---------------+
| 16 | 4 | Float | [1][0] |
+----------+-------+---------+---------------+
| 20 | 4 | Float | [1][1] |
+----------+-------+---------+---------------+
| 24 | 4 | Float | [1][2] |
+----------+-------+---------+---------------+
| 28 | 4 | Float | [2][0] |
+----------+-------+---------+---------------+
| 32 | 4 | Float | [2][1] |
+----------+-------+---------+---------------+
| 36 | 4 | Float | [2][2] |
+----------+-------+---------+---------------+
| 40 | 4 | Float | [3][0] |
+----------+-------+---------+---------------+
| 44 | 4 | Float | [3][1] |
+----------+-------+---------+---------------+
| 48 | 4 | Float | [3][2] |
+----------+-------+---------+---------------+
14: color
~~~~~~~~~
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | Red (0..1) |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Green (0..1) |
+----------+-------+---------+----------------+
| 12 | 4 | Float | Blue (0..1) |
+----------+-------+---------+----------------+
| 16 | 4 | Float | Alpha (0..1) |
+----------+-------+---------+----------------+
15: image
~~~~~~~~~
+---------------------+-------+-----------+------------------------------------------------------+
| Offset | Len | Type | Description |
+=====================+=======+===========+======================================================+
| 4 | 4 | Integer | Format (see FORMAT\_\* in \\"Image\\":class\_image |
+---------------------+-------+-----------+------------------------------------------------------+
| 8 | 4 | Integer | Mip-Maps (0 means no mip-maps). |
+---------------------+-------+-----------+------------------------------------------------------+
| 12 | 4 | Integer | Width (Pixels) |
+---------------------+-------+-----------+------------------------------------------------------+
| 16 | 4 | Integer | Height (Pixels) |
+---------------------+-------+-----------+------------------------------------------------------+
| 20 | 4 | Integer | Data Length |
+---------------------+-------+-----------+------------------------------------------------------+
| 24..24+DataLength | 1 | Byte | Image Data |
+---------------------+-------+-----------+------------------------------------------------------+
This field is padded to 4 bytes.
16: node path
~~~~~~~~~~~~~
+----------+-------+-----------+-----------------------------------------------------------------------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+=========================================================================================+
| 4 | 4 | Integer | String Length, or New Format (val&amp;0x80000000!=0 and NameCount=val&amp;0x7FFFFFFF) |
+----------+-------+-----------+-----------------------------------------------------------------------------------------+
For old format:
^^^^^^^^^^^^^^^
+----------+-------+---------+------------------------+
| Offset | Len | Type | Description |
+==========+=======+=========+========================+
| 8 | X | Bytes | UTF-8 Encoded String |
+----------+-------+---------+------------------------+
Padded to 4 bytes.
For new format:
^^^^^^^^^^^^^^^
+----------+-------+-----------+-------------------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+=====================================+
| 4 | 4 | Integer | Sub-Name Count |
+----------+-------+-----------+-------------------------------------+
| 8 | 4 | Integer | Flags (absolute: val&amp;1 != 0 ) |
+----------+-------+-----------+-------------------------------------+
For each Name and Sub-Name
+----------+-------+-----------+------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+========================+
| X+0 | 4 | Integer | String Length |
+----------+-------+-----------+------------------------+
| X+4 | X | Bytes | UTF-8 Encoded String |
+----------+-------+-----------+------------------------+
Every name string is is padded to 4 bytes.
17: rid (unsupported)
~~~~~~~~~~~~~~~~~~~~~
18: object (unsupported)
~~~~~~~~~~~~~~~~~~~~~~~~
19: input event
~~~~~~~~~~~~~~~
20: dictionary
~~~~~~~~~~~~~~
+----------+-------+-----------+---------------------------------------------------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+=====================================================================+
| 4 | 4 | Integer | val&amp;0x7FFFFFFF = elements, val&amp;0x80000000 = shared (bool) |
+----------+-------+-----------+---------------------------------------------------------------------+
| Then what follows is, for amount of \\"elements\\", pairs of key and
value, one after the other, using
| this same format.
21: array
~~~~~~~~~
+----------+-------+-----------+---------------------------------------------------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+=====================================================================+
| 4 | 4 | Integer | val&amp;0x7FFFFFFF = elements, val&amp;0x80000000 = shared (bool) |
+----------+-------+-----------+---------------------------------------------------------------------+
| Then what follows is, for amount of \\"elements\\", values one after
the other, using
| this same format.
22: byte array
~~~~~~~~~~~~~~
+---------------+-------+-----------+------------------------+
| Offset | Len | Type | Description |
+===============+=======+===========+========================+
| 4 | 4 | Integer | Array Length (Bytes) |
+---------------+-------+-----------+------------------------+
| 8..8+length | 1 | Byte | Byte (0..255) |
+---------------+-------+-----------+------------------------+
The array data is padded to 4 bytes.
23: int array
~~~~~~~~~~~~~
| Offset \| Len \| Type \| Description
| -- \| -- \| -- \| --
| 4\|4\|Integer\| Array Length (Integers)
| 8..8+length\*4\|4\|Integer\| 32 Bits Signed Integer
24: float array
~~~~~~~~~~~~~~~
| Offset \| Len \| Type \| Description
| -- \| -- \| -- \| --
| 4\|4\|Integer\| Array Length (Floats)
| 8..8+length\*4\|4\|Integer\| 32 Bits IEE 754 Float
25: string array
~~~~~~~~~~~~~~~~
+----------+-------+-----------+--------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+==========================+
| 4 | 4 | Integer | Array Length (Strings) |
+----------+-------+-----------+--------------------------+
For each String:
+----------+-------+-----------+------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+========================+
| X+0 | 4 | Integer | String Length |
+----------+-------+-----------+------------------------+
| X+4 | X | Bytes | UTF-8 Encoded String |
+----------+-------+-----------+------------------------+
Every string is is padded to 4 bytes.
26: vector2 array
~~~~~~~~~~~~~~~~~
+-------------------------------------------+-------+-----------+----------------+
| Offset | Len | Type | Description |
+===========================================+=======+===========+================+
| 4 | 4 | Integer | Array Length |
+-------------------------------------------+-------+-----------+----------------+
| 8..8+length\_8\|4\|Float\| X Coordinate | 4 | Float | Y Coordinate |
| 8..12+length\_8 | | | |
+-------------------------------------------+-------+-----------+----------------+
27: vector3 array
~~~~~~~~~~~~~~~~~
| Offset \| Len \| Type \| Description
| -- \| -- \| -- \| --
| 4\|4\|Integer\| Array Length
| 8..8+length\_12\|4\|Float\| X Coordinate
| 8..12+length\_12\|4\|Float\| Y Coordinate
| 8..16+length\*12\|4\|Float\| Z Coordinate
28: color array
~~~~~~~~~~~~~~~
+--------------------------------------------+-------+-----------+----------------+
| Offset | Len | Type | Description |
+============================================+=======+===========+================+
| 4 | 4 | Integer | Array Length |
+--------------------------------------------+-------+-----------+----------------+
| 8..8+length\_16\|4\|Float\| Red (0..1) | 4 | Float | Green (0..1) |
| 8..12+length\_16 | | | |
+--------------------------------------------+-------+-----------+----------------+
| 8..16+length\_16\|4\|Float\| Blue (0..1) | 4 | Float | Alpha (0..1) |
| 8..20+length\_16 | | | |
+--------------------------------------------+-------+-----------+----------------+

11
advanced_topics/changing_editor_fonts.rst Normal file
View File

@@ -0,0 +1,11 @@
Changing editor fonts
=====================
Godot allows changing the font for the editor, and the font for the code
editor. Both need to be in .fnt format, so they need to be imported
somewhere using the [[Importing fonts\|font import tool]].
Then copy or do whathever you want with the font, as long as the
location does not change, and set the relevant property in Editor
Settings. Code editor font is refreshed automatically, but the editor
needs to be restarted for the new global font to take effect.

145
advanced_topics/command_line_tutorial.rst Normal file
View File

@@ -0,0 +1,145 @@
Command line tutorial
=====================
Some developers like using the command line extensively. Godot is
designed to be friendly to them, so here are the steps for working
entirely from the command line. Given the engine relies on little to no
external libraries, initialization times are pretty fast, making it
suitable for this workflow.
Path
----
It is recommended that your godot binary is in your PATH environment
variable, so it can be executed easily from any place by typing
``godot``. You can do so on Linux by placing the Godot binary in
``/usr/local/bin`` and making sure it is called ``godot``.
Creating a project
------------------
Creating a project from the command line is simple, just navigate the
shell to the desired place and just make an engine.cfg file exist, even
if empty.
::
user@host:~$ mkdir newgame
user@host:~$ cd newgame
user@host:~/newgame$ touch engine.cfg
That alone makes for an empty Godot project.
Running the editor
------------------
Running the editor is done by executing godot with the ``-e`` flag. This
must be done from within the project directory, or a subdirectory,
otherwise the command is ignored and the project manager appears.
::
user@host:~/newgame$ godot -e
If a scene has been created and saved, it can be edited later by running
the same code with that scene as argument.
::
user@host:~/newgame$ godot -e scene.xml
Erasing a scene
---------------
Godot is friends with your filesystem, and will not create extra
metadata files, simply use ``rm`` to erase a file. Make sure nothing
references that scene, or else an error will be thrown upon opening.
::
user@host:~/newgame$ rm scene.xml
Running the game
----------------
To run the game, simply execute Godot within the project directory or
subdirectory.
::
user@host:~/newgame$ godot
When a specific scene needs to be tested, pass that scene to the command
line.
::
user@host:~/newgame$ godot scene.xml
Debugging
---------
Catching errors in the command line can be a difficult task because they
just fly by. For this, a command line debugger is provided by adding
``-d``. It works for both running the game or a simple scene.
::
user@host:~/newgame$ godot -d
::
user@host:~/newgame$ godot -d scene.xml
Exporting
---------
Exporting the project from the command line is also supported. This is
specially useful for continuous integration setups. The version of Godot
that is headless (server build, no video) is ideal for this.
::
user@host:~/newgame$ godot -export \"Linux X11\" /var/builds/project
user@host:~/newgame$ godot -export Android /var/builds/project.apk
The platform names recognized by the ``-export`` switch are the same as
displayed in the export wizard of the editor. To get a list of supported
platforms from the command line, just try exporting to a non-recognized
platform and the full listing of platforms your configuration supports
will be shown.
To export a debug version of the game, use the ``-export_debug`` switch
instead of ``-export``. Their parameters and usage are the same.
Running a script
----------------
| It is possible to run a simple .gd script from the command line. This
feature is specially useful in very large projects, for batch
conversion of assets or custom import/export.
| The script must inherit from SceneTree or MainLoop.
Here is a simple example of how it works:
| <pre class=\\"python\\">
| #sayhello.gd
| extends SceneTree
| func \_init():
| print(\\"Hello!\\")
| quit()
.. raw:: html
</pre>
And how to run it:
::
user@host:~/newgame$ godot -s sayhello.gd
Hello!
If no engine.cfg exists at the path, current path is assumed to be the
current working directory (unless ``-path`` is specified).

21
advanced_topics/compiling.rst Normal file
View File

@@ -0,0 +1,21 @@
Compiling
=========
.. toctree::
:maxdepth: 1
:name: compiling
introduction_to_the_buildsystem
compiling_for_windows
compiling_for_linux
compiling_for_osx
compiling_for_android
compiling_for_ios
cross-compiling_for_ios_on_linux
compiling_for_universal_windows_apps
batch_building_templates
configure_your_ide
introduction_to_godot_development
.. compiling_for_blackberry_qnx
.. compiling_for_google_native_client

224
advanced_topics/compiling_for_android.rst Normal file
View File

@@ -0,0 +1,224 @@
Compiling for Android
=====================
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 [[Exporting
for Android]] tutorial before attempting your custom export template.
Requirements
------------
For compiling under Windows, the following is required:
- Python 2.7+ (3.0 is untested as of now).
- SCons build system.
- Android SDK version 8 and 13
- Android NDK
Setting Up SCons
----------------
| Set the environment variable ANDROID\_HOME to point to the Android
SDK.
| Set the environment variable ANDROID\_NDK\_ROOT to point to the
Android NDK.
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 Linux, use
``export ANDROID_HOME=/path/to/android-sdk`` and
``export ANDROID_NDK_ROOT=/path/to/android-ndk``.
Compiling
---------
Go to the root dir of the engine source code and type:
::
C:\\godot> scons platform=android
This should result in a regular .so in \\\\bin folder as if it was
compiled with flags: ``tools=no target=debug``. The resulting file will
be huge because it will contain all debug symbols, so for next builds,
using ``target=release_debug`` or ``target=release`` is recommended.
Copy the .so to the libs/armeabi Android folder (or symlink if you are
in Linux or OSX). Note: Git does not support empty directories so you
will have to create it if it does not exist:
::
C:\\godot> mkdir platform/android/java/libs
C:\\godot> mkdir platform/android/java/libs/armeabi
Then copy or symlink:
::
C:\\godot> copy bin/libgodot.android..so platform/android/java/libs/armeabi/libgodot_android.so
alternatively if you are under unix you can symlink:
::
user@host:~/godot$ ln -s bin/libgodot.android..so platform/android/java/libs/armeabi/libgodot_android.so
Remember that only *one* of libgodot\_android.so must exist for each
platform, for each build type (release, debug, etc), it must be
replaced.
**Note**: The file inside libs/armeabi must be renamed to
**\\"libgodot\_android.so\\"**, or else unsatisfied link error will
happen at runtime.
If you also want to include support for x86 Android, add the following
compile flag: ``x86=yes`` , then copy/symlink the resulting folder to
the x86 folder:
::
C:\\godot> cp bin/libgodot.android..x86.so platform/android/java/libs/x86/libgodot_android.so
This will create a fat binary that works in both platforms, but will add
about 6 megabytes to the APK.
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 numbers, then set the following environment variables:
::
NDK_TOOLCHAIN (by default set to \"arm-eabi-4.4.0\")
NDK_TARGET (by default set to \"arm-linux-androideabi-4.8\")
Building the APK
----------------
To compile the APK, go to the Java folder and run ant, either for debug
or release build:
::
C:\\godot\\platform\\android\\java> ant debug
::
C:\\godot\\platform\\android\\java> ant release
In the ``java/bin`` subfolder, the resulting apk can be used as export
template.
**Note:** If you reaaaally feel oldschool, you can copy your entire game
(or symlink) to the assets/ folder of the Java project (make sure
engine.cfg is in assets/) and it will work, but you lose all the
benefits of the export system (scripts are not byte-compiled, textures
not converted to Android compression, etc. so it's not a good idea).
Compiling export templates
--------------------------
Godot needs the freshly compiled APK as export templates. It 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).
Compiling the standard export templates is done by calling scons with
the following arguments:
(debug)
::
C:\\godot> scons platform=android target=release_debug
C:\\godot> cp bin/libgodot_android.opt.debug.so platform/android/java/libs/armeabi
C:\\godot> cd platform/android/java
C:\\godot\\platform\\android\\java> ant release
Resulting APK is in:
::
platform/android/java/bin/Godot-release-unsigned.apk
(release)
::
C:\\godot> scons platform=android target=release
C:\\godot> cp bin/libgodot_android.opt.so platform/android/java/libs/armeabi
C:\\godot> cd platform/android/java
C:\\godot\\platform\\android\\java> ant release
Resulting APK is in:
::
platform/android/java/bin/Godot-release-unsigned.apk
(same as before)
They must be copied to your templates folder with the following names:
::
android_debug.apk
android_release.apk
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 the next
time you build you 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 JDK6.
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:
- libgodot\_android.so is not in libs/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.

44
advanced_topics/compiling_for_ios.rst Normal file
View File

@@ -0,0 +1,44 @@
Compiling for iOS
=================
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 bin/godot.iphone.debug
for a debug build, or:
::
$ scons p=iphone bin/godot.iphone.opt 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=isim bin/godot.isim.tools
for a Simulator executable.
Run
---
| To run on a device or simulator, follow these instructions:
[[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.

102
advanced_topics/compiling_for_linux.rst Normal file
View File

@@ -0,0 +1,102 @@
Compiling for Linux
===================
Requirements
------------
For compiling under Linux or other Unix variants, the following is
required:
- GCC or LLVM
- Python 2.7+ (3.0 is untested as of now).
- SCons build system.
- X11 and MESA development Libraries
- Xinerama Libraries
- ALSA development libraries
- Freetype (for the editor)
- OpenSSL (for HTTPS and TLS)
- pkg-config (used to detect the above three)
- libevdev-dev and libudev-dev (for facultative joypad support)
For Ubuntu users:
::
apt-get install scons pkg-config libx11-dev libxcursor-dev build-essential libasound2-dev libfreetype6-dev libgl1-mesa-dev libglu-dev libssl-dev libxinerama-dev
If you wish to have Joypad support, libevdev-dev and libudev-dev are
required.
::
apt-get install libevdev-dev libudev-dev
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.
Building export templates
-------------------------
To build Linux 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 in linux is quite difficult and might need a chroot
environment.
In Ubuntu, compilation works without a chroot but some libraries (.so)
might be missing from /usr/lib32. Symlinking the missing .so files from
/usr/lib results in a working build.
To create standard export templates, the resulting files must be copied
to:
::
/home/youruser/.godot/templates
and named like this:
::
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.

63
advanced_topics/compiling_for_osx.rst Normal file
View File

@@ -0,0 +1,63 @@
Compiling for OSX
=================
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
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. There is a .app template to put the binary into in
tools/Godot.app.
Cross-compiling
---------------
It is possible to compile for OS X in a Linux environment (and maybe
also in Windows with Cygwin). For that you will need
\\\ `OSXCross\\ <https://github.com/tpoechtrager/osxcross>`__ for being
able to use OS X as target. First, follow the instructions to install
it:
# Clone the OSXCross repository
(https://github.com/tpoechtrager/osxcross) somewhere in your machine (or
download a Zip file and extract it somewhere). E.g.
::
~$ git clone https://github.com/tpoechtrager/osxcross.git /home/myuser/sources/osxcross
#. Follow the instructions to package the SDK:
https://github.com/tpoechtrager/osxcross#packaging-the-sdk
#. 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.
::
~$ export OSXCROSS_ROOT=/home/myuser/sources/oscross
Now you can compile with SCons like you normally would:
::
~/godot$ scons platform=osx

148
advanced_topics/compiling_for_universal_windows_apps.rst Normal file
View File

@@ -0,0 +1,148 @@
Compiling for Universal Windows Apps
====================================
This page documents the current state of the \\"winrt\\" platform, used
to support \\"Windows Store Apps\\" for Windows 8.1, and Windows Phone
8.1 apps using Microsoft's new \\"Universal\\" APIs.
Requirements
------------
- Windows 8
- SCons (see [[Compiling for Windows]] for more details)
- Visual Studio 2013 for Windows (but *not* \\"for Windows Desktop\\").
Tested on \\"Microsoft Visual Studio Express 2013 for Windows Version
12.0.31101.00 Update 4\\".
Compiling
---------
The platform can compile binaries for both Windows 8.1 and Windows Phone
8.1. The architecture is decided by the environment variable
\\"PLATFORM\\".
Windows 8.1
~~~~~~~~~~~
\* Open a \\"VS 2013 x64 Cross Tools Command Prompt\\"
\* The value of environment variable \\"PLATFORM\\" should be \\"x64\\"
\* Run scons with platform=winrt from the root of the source tree
::
C:\\godot_source> scons platform=winrt
- You should get an executable file inside bin/ named according to your
build options, for the architecture \\"x64\\", for example
\\"godot.winrt.tools.x64.exe\\".
Windows Phone 8.1
~~~~~~~~~~~~~~~~~
\* Open a \\"Visual Studio 2012 ARM Phone Tools Command Prompt\\"
\* The value of environment variable \\"PLATFORM\\" should be \\"arm\\"
\* Run scons with platform=winrt from the root of the source tree
::
C:\\godot_source> scons platform=winrt
- You should get an executable file inside bin/ named according to your
build options, for the architecture \\"arm\\", for example
\\"godot.winrt.tools.arm.exe\\".
Running
-------
On Visual studio, create a new project using any of the \\"Unversal
App\\" templates found under Visual C++ -> Store Apps -> Universal Apps.
\\"Blank App\\" should be fine.
On the \\"Solution Explorer\\" box, you should have 3 sections,
\\"App.Windows (Windows 8.1)\\", \\"App.WindowsPhone (Windows Phone
8.1)\\" and \\"App.Shared\\". You need to add files to each section:
App.Shared
~~~~~~~~~~
- Add a folder named \\"game\\" containing your game content (can be
individual files or your data.pck). Remember to set the \\"Content\\"
property of each file to \\"True\\", otherwise your files won't get
included in the package.
App.Windows
~~~~~~~~~~~
\* Add your windows executable, and all the .dll files found on
platform/winrt/x64/bin on the godot source. Remember to also set the
\\"Content\\" property.
\* Find the file \\"Package.appxmanifest\\". Right click on it and
select \\"Open with...\\" then \\"XML (Text) Editor\\" from the list.
\* Find the \\"Application\\" section, and add (or modify) the
\\"Executable\\" property with the name of your .exe. Example:
::
App.WindowsPhone
~~~~~~~~~~~~~~~~
- Repeat all the steps from App.Windows, using your arm executable and
the dlls found in platform/winrt/arm/bin. Remember to set the
\\"Content\\" property for all the files.
Use the green \\"Play\\" button on the top to run. The drop down menu
next to it should let you choose the project (App.Windows or
App.WindowsPhone) and the device (\\"Local Machine\\", \\"Device\\" for
an attached phone, etc).
Angle
-----
ANGLE precompiled binaries are provided on platform/winrt/x64 and
platform/winrt/arm. They are built from MSOpenTech's \\"future-dev\\"
branch, found here:
\\\ `https://github.com/MSOpenTech/angle\\ <https://github.com/MSOpenTech/angle>`__.
The visual studio 'solutions' used are found on
\\"projects/winrt/windows/angle.sln\\" and
\\"projects/winrt/windowsphone/angle.sln\\".
What's missing
--------------
- Audio
- Semaphores
- Keyboard input
- Proper handling of screen rotation
- Proper handling of other events such as focus lost, back button, etc.
- Packaging and deploying to devices from the editor.
- Adding Angle to our tree and compiling it from there. The same source
could also be used to build for Windows (and use Angle instead of
native GL, which will be more compatible with graphics hardware)
Packages
--------
This is what we know:
- App packages are documented here:
\\\ `http://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh464929.aspx\\ <http://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh464929.aspx>`__
- There are 2 command line tools that might be useful, \\\ `App
Packager\\ <http://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh446767.aspx>`__
and
\\\ `SignTool\\ <http://msdn.microsoft.com/en-us/library/windows/apps/xaml/ff551778.aspx>`__.
- There are a bunch of tools on \\"powershell\\" that deal with
packages that might be relevant:
\\\ `http://technet.microsoft.com/library/dn448373.aspx\\ <http://technet.microsoft.com/library/dn448373.aspx>`__
- When running a Windows 8.1 app on \\"Local Machine\\" from Visual
studio, the app seems to run from an uncompressed directory on the
filesystem in an arbitrary location (ie. outside of the proper
directory where Apps are installed), but there is some special
registry entry made for it, so we know it's possible to skip the
packaging step to run locally (in the case of very big games this can
be useful).

151
advanced_topics/compiling_for_windows.rst Normal file
View File

@@ -0,0 +1,151 @@
Compiling for Windows
=====================
Requirements
------------
For compiling under Windows, the following is required:
- \\\ `Visual C++\\ <http://www.microsoft.com/visualstudio>`__, Visual
C++ Express compiler or Visual Studio Community (recommended) at
least the 2010 version (10.0) up to 2015 (14.0). **Make sure you get
a version that can compile for C++, Desktop**.
- \\\ `Python 2.7+\\ <http://www.python.org/getit/releases/2.7/>`__
(3.0 is untested as of now). Using the 32-bits installer is
recommended.
- \\\ `Pywin32 Python
Extension\\ <http://sourceforge.net/projects/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 and provides a .bat file called
\\"scons.bat\\". The location of this file can be added to the path or
it can simply be copied to C:\\\\Python together with the interpreter
executable.
Compiling
---------
Start a Visual Studio command prompt (it sets up environment variables
needed by SCons to locate the compiler and SDK), go to the root dir of
the engine source code and type:
::
C:\\godot> scons platform=windows
If all goes well, the resulting binary executable will be placed in
C:\\\\godot\\\\bin\\\\godot.windows.tools.exe. This executable file
contains the whole engine and runs without any dependencies. Executing
it will bring up the project manager.
Development in Visual Studio or other IDEs
------------------------------------------
For most projects, using only scripting is enough but when development
in C++ is needed, for creating modules or extending the engine, working
with an IDE is usually desirable. The visual studio command prompt calls
a .bat file that sets up environment variables (vcvarsall.bat). To build
the whole engine from a single command outside the command prompt, the
following should be called in a .bat file:
::
C:\\path_to_sdk\\vcvarsall.bat && scons bin/godot.windows.tools.exe
**NOTE:** It seems the latest Visual Studio does not include a desktop
command prompt (No, Native tools for x86 is not it). The only way to
build it seems to be by running:
::
\"C:\\Program Files (x86)\\Microsoft Visual Studio 12.0\\VC\\vcvarsall.bat\" && c:\\python27\\scons p=windows
(or however your VS and Scons are installed)
Cross compiling
---------------
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 other 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:
(for 32 bits, using Mingw32 command prompt or Visual Studio command
prompt)
::
C:\\godot> scons platform=windows tools=no target=release bits=32
C:\\godot> scons platform=windows tools=no target=release_debug bits=32
(for 64 bits, using Mingw-w64 or Visual Studio command prompt)
::
C:\\godot> scons platform=windows tools=no target=release bits=64
C:\\godot> scons platform=windows tools=no target=release_debug bits=64
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.

11
advanced_topics/configure_your_ide.rst Normal file
View File

@@ -0,0 +1,11 @@
Configure an IDE
================
With Eclipse
------------
With QtCreator
--------------
With another editor (vim, emacs, Atom...)
-----------------------------------------

231
advanced_topics/core_types.rst Normal file
View File

@@ -0,0 +1,231 @@
Core types
==========
| Godot has a rich set of classes and template that make for 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 neccesary. 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/okamstudio/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 an 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:
::
memalloc()
memrealloc()
memfree()
These are equivalent to the usual malloc, realloc, free of the standard
library.
For C++-style allocation, special macros are provided:
::
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:
::
DVector
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:
::
DVector::Read r = dvector.read()
int someint = r[4]
and
::
DVector::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/okamstudio/godot/blob/master/core/os/memory.h>`__
- \\\ `core/dvector.h\\ <https://github.com/okamstudio/godot/blob/master/core/dvector.h>`__
Containers
----------
Godot provides also a set of common containers:
- Vector
- List
- Set
- Map
The 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:
::
for(List::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/okamstudio/godot/blob/master/core/vector.h>`__
- \\\ `core/list.h\\ <https://github.com/okamstudio/godot/blob/master/core/list.h>`__
- \\\ `core/set.h\\ <https://github.com/okamstudio/godot/blob/master/core/set.h>`__
- \\\ `core/map.h\\ <https://github.com/okamstudio/godot/blob/master/core/map.h>`__
String
------
Godot also provides a String class. This class has a huge amoun of
features, full Unicode support in all the functions (like case
operations) and utf8 parsing/exracting, as well as helpers for
conversion and visualization.
References:
~~~~~~~~~~~
- \\\ `core/ustring.h\\ <https://github.com/okamstudio/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/okamstudio/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/okamstudio/godot/blob/master/core/math>`__
NodePath
--------
This is a special datatype sued for storing paths in a scenetree and
referencing them fast.
References:
~~~~~~~~~~~
- \\\ `core/path\_db.h\\ <https://github.com/okamstudio/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/okamstudio/godot/blob/master/core/rid.h>`__

354
advanced_topics/creating_android_modules.rst Normal file
View File

@@ -0,0 +1,354 @@
Creating Android modules
========================
Introduction
------------
| Making videogames 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 [[Custom modules in C++]], but
needs a few more steps.
Make sure you are familiar with building your own [[Compiling for
Android\|Android export templates]], as well as creating [[Custom
modules in C++\|custom modules]].
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:
| <pre class=\\"python\\">
| def can\_build(plat):
| return plat==\\"android\\"
.. raw:: html
</pre>
If more than one platform can be built (typical if implementing the
module also for iOS), check manually for Android in the configure
functions:
| <pre class=\\"python\\">
| def can\_build(plat):
| return plat\\"android\\" or plat\\"iphone\\"
| def configure(env):
| if env['platform'] == 'android':
| #androd specific code
.. raw:: html
</pre>
Java singleton
--------------
An android module will usually have a singleton class that will load it,
this class inherits from ``Godot.SingletonBase``. A singleton object
template follows:
| <pre class=\\"java\\">
| //namespace is wrong, will eventually change
| package com.android.godot;
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
}
.. raw:: html
</pre>
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:
<pre class=\\"java\\">GodotLib.calldeferred(, \\"\\", new
Object[]{param1,param2,etc});
.. raw:: html
</pre>
Add this singleton to the build of the project by adding the following
to config.py:
| <pre class=\\"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
.. raw:: html
</pre>
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:
| <pre class=\\"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\\")
.. raw:: html
</pre>
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:
| <pre class=\\"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\\")
.. raw:: html
</pre>
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, should be reflected in the manifest template:
\\\ `https://github.com/okamstudio/godot/blob/master/platform/android/AndroidManifest.xml.template\\ <https://github.com/okamstudio/godot/blob/master/platform/android/AndroidManifest.xml.template>`__
Then, add the module folder to the project:
| <pre class=\\"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\\",\\"\\")
.. raw:: html
</pre>
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 build the ant project normally:
::
c:\\godot\\platform\\android\\java> ant release
This should generate the apk used as export template properly, as
defined in the [[Compiling for Android\|Android build instructions]].
Usually to generate the apk, again both commands must be run in
sequence:
::
c:\\godot> scons p=android
c:\\godot\\platform\\android\\java> ant release
Using the Module
~~~~~~~~~~~~~~~~
To use the Module from GDScript, first enable the singleton by adding
the following line to engine.cfg:
::
[android]
modules=\"com/android/godot/MySingleton\"
More than one singleton module can be enable by separating with comma:
::
[android]
modules=\"com/android/godot/MySingleton,com/android/godot/MyOtherSingleton\"
Then just request the singleton Java object from Globals like this:
| <pre class=\\"python\\">
| #in any file
var singleton=null
| func \_init():
| singleton = Globals.get\_singleton(\\"MySingleton\\")
| print( singleton.myFunction(\\"Hello\\") )
.. raw:: html
</pre>
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 fro GDScript.
| It's simple to use and it's used like this:
::
class = JavaClassWrapper.wrap()
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>`__.

157
advanced_topics/cross-compiling_for_ios_on_linux.rst Normal file
View File

@@ -0,0 +1,157 @@
Cross-compiling for iOS on Linux
================================
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 do 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 needs 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 in your machine:
::
$ git clone https://github.com/LubosD/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 have, 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 bits=32 target=release_debug IPHONESDK=\"/path/to/iPhoneSDK\" IPHONEPATH=\"/path/to/iostoolchain\" ios_triple=\"arm-apple-darwin11-\"
$ scons -j 4 platform=iphone bits=64 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 achitectures (``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.32 bin/godot.iphone.opt.debug.64 -output bin/godot.iphone.opt.debug.fat
Then you will have an iOS fat binary in
``bin/godot.iphone.opt.debug.fat``.

258
advanced_topics/custom_modules_in_c++.rst Normal file
View File

@@ -0,0 +1,258 @@
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 them modules/ subdirectory of the build system.
By default, two modules exist, GDScript (which, yes it's 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 wiki 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:
| <pre class=\\"cpp\\">
| /\* sumator.h \*/
| #ifndef SUMATOR\_H
| #define SUMATOR\_H
#include "reference.h&quot;
| 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
.. raw:: html
</pre>
And then the cpp file.
| <pre class=\\"cpp\\">
| /\* sumator.cpp \*/
#include "sumator.h&quot;
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&quot;,&Sumator::add);
| ObjectTypeDB::bind\_method("reset&quot;,&Sumator::reset);
| ObjectTypeDB::bind\_method("get\_total&quot;,&Sumator::get\_total);
| }
| Sumator::Sumator() {
| count=0;
| }
.. raw:: html
</pre>
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
| <pre class=\\"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 \*/
.. raw:: html
</pre>
| <pre class=\\"cpp\\">
| /\* register\_types.cpp \*/
| #include "register\_types.h&quot;
| #include "object\_type\_db.h&quot;
| #include "sumator.h&quot;
void register\_sumator\_types() {
| ObjectTypeDB::register\_type&lt;Sumator&gt;();
| }
| void unregister\_sumator\_types() {
| //nothing to do here
| }
.. raw:: html
</pre>
Next, we need to create a SCsub so the build system compiles this
module:
<pre class=\\"python\\">
#. SCsub
Import('env')
env.add\_source\_files(env.modules\_sources,"\*.cpp&quot;) # just add
all cpp files to the build
.. raw:: html
</pre>
And finally, the configuration file for the module, this is a simple
python script that must be named 'config.py'
<pre class=\\"python\\">
#. config.py
| def can\_build(platform):
| return True
| def configure(env):
| pass
.. raw:: html
</pre>
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).
The second function allows to customize the build process for the
module, like adding special compiler flags, options etc. (This can be
done in SCSub, but configure(env) is called at a previous stage). If
unsure, just ignore this.
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 section), your
module will be included.
Using the module
----------------
Using your newly created module is very easy, from any script you can
do:
| <pre class=\\"python\\">
| var s = Sumator.new()
| s.add(10)
| s.add(20)
| s.add(30)
| print( s.get\_total() )
| s.reset()
.. raw:: html
</pre>
And the output will be ``60``.
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 [[API: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 [[API:Resource]], it will appear int 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.

13
advanced_topics/developing.rst Normal file
View File

@@ -0,0 +1,13 @@
Developing in C++
=================
.. toctree::
:maxdepth: 1
:name: developing-in-c++
core_types
variant_class
object_class
custom_modules_in_c++
creating_android_modules

8
advanced_topics/formats.rst Normal file
View File

@@ -0,0 +1,8 @@
Data and file formats
=====================
.. toctree::
:maxdepth: 1
:name: data-and-file-formats
binary_serialization_api

11
advanced_topics/index.rst Normal file
View File

@@ -0,0 +1,11 @@
Advanced topics
===============
.. toctree::
:maxdepth: 2
:name: advanced-topics
compiling
developing
formats
misc

13
advanced_topics/introduction_to_godot_development.rst Normal file
View File

@@ -0,0 +1,13 @@
Introduction to Godot development
=================================
This page introduces the global organization of Godot Engine's source
code.
Debugging the editor with gdb
-----------------------------
If you are writing or correcting bugs affecting Godot Engine editor,
remember that the binary runs the launcher first, which runs the editor
in another process. Thus, you need to run the editor directly by passing
the ``-e`` argument to Godot Engine editor's binary.

218
advanced_topics/introduction_to_the_buildsystem.rst Normal file
View File

@@ -0,0 +1,218 @@
Introduction to the buildsystem
===============================
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 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 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 processes:
::
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..[opt].[tools/debug]..
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
http://www.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= 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= target=debug/release_debug/release
This flag appends \\".debug\\" suffix (for debug), or \\".tools\\" (for
debug with tools enables). 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= 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:
http://www.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
windows_debug.exe
windows_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 it's 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.

11
advanced_topics/misc.rst Normal file
View File

@@ -0,0 +1,11 @@
Misc
====
.. toctree::
:maxdepth: 1
:name: misc
command_line_tutorial
changing_editor_fonts
services_for_ios

369
advanced_topics/object_class.rst Normal file
View File

@@ -0,0 +1,369 @@
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.
| <pre class=\\"cpp\\">
| class CustomObject : public Object {
| OBJ\_TYPE(CustomObject,Object); // this required to inherit
| };
.. raw:: html
</pre>
This makes objects gain a lot of functionality, like for example
| <pre class=\\"cpp\\">
| obj = memnew(CustomObject);
| print\_line("Object Type: ",obj->get\_type()); //print object type
obj2 = obj->cast\_to&lt;OtherType&gt;(); // converting between types,
this also works without RTTI enabled.
.. raw:: html
</pre>
References:
~~~~~~~~~~~
- \\\ `core/object.h\\ <https://github.com/okamstudio/godot/blob/master/core/object.h>`__
Registering an Object
---------------------
ObjectTypeDB is a static class that hold 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:
<pre class=\\"cpp\\">ObjectTypeDB::register\_type()
.. raw:: html
</pre>
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.
<pre class=\\"cpp\\">ObjectTypeDB::register\_virtual\_type()
.. raw:: html
</pre>
Object derived classes can override a 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:
<pre
class=\\"cpp\\">ObjectTypeDB::register\_method(\_MD (\\"methodname\\",\\"arg1name\\",\\"arg2name\\"),&MyCustethod);
.. raw:: html
</pre>
Default values for arguments can be passed in reverse order:
<pre
class=\\"cpp\\">ObjectTypeDB::register\_method(\_MD (\\"methodname\\",\\"arg1name\\",\\"arg2name\\"),&MyCustomType::method,DEFVAL (-1));
//default argument for arg2name
.. raw:: html
</pre>
``_MD`` is a macro that convers \\"methodname\\" to a stringname for
more efficiency. Argument names are used for instrospection, 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 throughly, the ``_MD()`` macro can safely be ignore and a
string passing the name can be passed for brevity.
References:
~~~~~~~~~~~
- \\\ `core/object\_type\_db.h\\ <https://github.com/okamstudio/godot/blob/master/core/object_type_db.h>`__
Constants
---------
Classes often have enums such as:
| <pre class=\\"cpp\\">
| enum SomeMode {
| MODE\_FIRST,
| MODE\_SECOND
| };
.. raw:: html
</pre>
For these to work when binding to methods, the enum must be declared
convertible to int, for this a macro is provided:
<pre class=\\"cpp\\">VARIANT\_ENUM\_CAST( MyClass::SomeMode); // now
functions that take SomeMode can be bound.
.. raw:: html
</pre>
The constants can also be bound inside ``_bind_methods``, by using:
| <pre class=\\"cpp\\">
| BIND\_CONSTANT( MODE\_FIRST );
| BIND\_CONSTANT( MODE\_SECOND );
.. raw:: html
</pre>
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:
<pre
class=\\"cpp\\">PropertyInfo(type,name,hint,hint\_string,usage\_flags)
.. raw:: html
</pre>
For example:
<pre
class=\\"cpp\\">PropertyInfo(Variant::INT,\\"amount\\",PROPERTY\_HINT\_RANGE,\\"0,49,1\\",PROPERTY\_USAGE\_EDITOR)
.. raw:: html
</pre>
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 wont be serialized.
or
<pre
class=\\"cpp\\">PropertyInfo(Variant::STRING,\\"modes\\",PROPERTY\_HINT\_ENUM,\\"Enabled,Disabled,Turbo\\")
.. raw:: html
</pre>
This is a string property, can take any string but the editor will only
allow the defined hint ones. Since no hint flags were specified, the
default ones are PROPERTY\_USAGE\_STORAGE and PROPERTY\_USAGE\_EDITOR.
There are plenty of hints and usages available in object.h, give them a
check.
Properties can also work like C# properties and be accessed from script
using indexing, but ths 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
imposssible unless using operator [].
From ``_bind_methods()``, properties can be created and bound as long as
a set/get functions exist. Example:
<pre class=\\"cpp\\">ADD\_PROPERTY(
PropertyInfo(Variant::INT,\\"amount\\"), \_SCS (\\"set\_amount\\"),
\_SCS (\\"get\_amount\\") )
.. raw:: html
</pre>
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 overriden 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).
| <pre class=\\"cpp\\">
| void \_get\_property\_info(List \*r\_props); //return list of
propertes
| 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
.. raw:: html
</pre>
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:
| <pre class=\\"cpp\\">
| void somefunc(Object \*some\_obj) {
| Button \* button = some\_obj->cast\_to&lt;Button&gt;();
| }
.. raw:: html
</pre>
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:
| <pre class=\\"cpp\\">
| obj->connect(,target\_instance,target\_method)
| //for example
| obj->connect(\\"enter\_tree\\",this,\\"\_node\_entered\_tree\\")
.. raw:: html
</pre>
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:
<pre class=\\"cpp\\">ADD\_SIGNAL( MethodInfo(\\"been\_killed\\") )
.. raw:: html
</pre>
References
----------
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.
| <pre class=\\"cpp\\">
| class MyReference: public Reference {
| OBJ\_TYPE( MyReference ,Reference);
| };
Ref myref = memnew( MyReference );
.. raw:: html
</pre>
``myref`` is reference counted. It will be freed when no more Ref<>
templates point to it.
References:
~~~~~~~~~~~
- \\\ `core/reference.h\\ <https://github.com/okamstudio/godot/blob/master/core/reference.h>`__
Resources:
----------
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/okamstudio/godot/blob/master/core/resource.h>`__
Resource loading
----------------
Resources can be loaded with the ResourceLoader API, like this:
<pre class=\\"cpp\\">Ref res =
ResourceLoader::load(\\"res://someresource.res\\")
.. raw:: html
</pre>
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/okamstudio/godot/blob/master/core/io/resource_loader.h>`__
Resource saving
---------------
Saving a resource can be done with the resource saver API:
<pre
class=\\"cpp\\">ResourceSaver::save(\\"res://someresource.res\\",instance)
.. raw:: html
</pre>
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://somereource.res::1\\". This also helps to cache them when
loaded.
References:
~~~~~~~~~~~
- \\\ `core/io/resource\_saver.h\\ <https://github.com/okamstudio/godot/blob/master/core/io/resource_saver.h>`__

434
advanced_topics/services_for_ios.rst Normal file
View File

@@ -0,0 +1,434 @@
Services for iOS
================
At the moment, there are 2 iOS APIs partially implemented, GameCenter
and Storekit. Both use the same model of asynchronous calls explained
below.
Asynchronous methods
--------------------
When requesting an asynchronous operation, the method will look like
this:
::
Error purchase(Variant p_params);
The parameter will usually be a Dictionary, with the information
necessary to make the request, and the call will have 2 phases. First,
the method will immediately return an Error value. If the Error is not
'OK', the call operation is completed, with an error probably caused
locally (no internet connection, API incorrectly configured, etc). If
the error value is 'OK', a response event will be produced and added to
the 'pending events' queue. Example:
| <pre class=\\"python\\">
| func on\_purchase\_pressed():
| var result = InAppStore.purchase( { \\\ `product\_id\\ <>`__
\\"my\_product\\" } )
| if result == OK:
| animation.play(\\"busy\\") # show the \\"waiting for response\\"
animation
| else:
| show\_error()
| # put this on a 1 second timer or something
| func check\_events():
| while InAppStore.get\_pending\_event\_count() > 0:
| var event = InAppStore.pop\_pending\_event()
| if event.type \\"purchase\\":
if event.result \\\ `ok\\ <>`__
| show\_success(event.product\_id)
| else:
| show\_error()
.. raw:: html
</pre>
Remember that when a call returns OK, the API will *always* produce an
event through the pending\_event interface, even if it's an error, or a
network timeout, etc. You should be able to, for example, safely block
the interface waiting for a reply from the server. If any of the APIs
don't behave this way it should be treated as a bug.
The pending event interface consists of 2 methods:
- ``get_pending_event_count()``
Returns the number of pending events on the queue.
- ``Variant pop_pending_event()``
Pops the first event from the queue and returns it.
Store Kit
---------
Implemented in platform/iphone/in\_app\_store.mm
The Store Kit API is accessible through the \\"InAppStore\\" singleton
(will always be available from gdscript). It is initialized
automatically. It has 2 methods for purchasing:
- ``Error purchase(Variant p_params);``
- ``Error request_product_info(Variant p_params);``
and the pending\_event interface
::
int get_pending_event_count();
Variant pop_pending_event();
purchase
~~~~~~~~
Purchases a product id through the Store Kit API.
Parameters
^^^^^^^^^^
Takes a Dictionary as a parameter, with one field, ``product_id``, a
string with your product id. Example:
::
var result = InAppStore.purchase( { \"product_id\": \"my_product\" } )
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
On error:
::
{
\"type\": \"purchase\",
\"result\": \"error\",
\"product_id\": \"the product id requested\"
}
On success:
::
{
\"type\": \"purchase\",
\"result\": \"ok\",
\"product_id\": \"the product id requested\"
}
request\_product\_info
~~~~~~~~~~~~~~~~~~~~~~
Requests the product info on a list of product IDs.
Parameters
^^^^^^^^^^
Takes a Dictionary as a parameter, with one field, ``product_ids``, a
string array with a list of product ids. Example:
::
var result = InAppStore.request_product_info( { \"product_ids\": [\"my_product1\", \"my_product2\"] } )
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
::
{
\"type\": \"product_info\",
\"result\": \"ok\",
\"invalid_ids\": [ list of requested ids that were invalid ],
\"ids\": [ list of ids that were valid ],
\"titles\": [ list of valid product titles (corresponds with list of valid ids) ],
\"descriptions\": [ list of valid product descriptions ] ,
\"prices\": [ list of valid product prices ],
\"localized_prices\": [ list of valid product localized prices ],
}
Game Center
-----------
Implemented in platform/iphone/game\_center.mm
The Game Center API is available through the \\"GameCenter\\" singleton.
It has 6 methods:
- ``Error post_score(Variant p_score);``
- ``Erroraward_achievement(Variant p_params);``
- ``Error reset_achievements();``
- ``Error request_achievements();``
- ``Error request_achievement_descriptions();``
- ``Error show_game_center(Variant p_params);``
plus the standard pending event interface.
post\_score
~~~~~~~~~~~
Posts a score to a Game Center leaderboard.
Parameters
^^^^^^^^^^
Takes a Dictionary as a parameter, with 2 fields:
- ``score`` a float number
- ``category`` a string with the category name
Example:
::
var result = GameCenter.post_score( { \"value\": 100, \"category\": \"my_leaderboard\", } )
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
On error:
::
{
\"type\": \"post_score\",
\"result\": \"error\",
\"error_code\": the value from NSError::code,
\"error_description\": the value from NSError::localizedDescription,
}
On success:
::
{
\"type\": \"post_score\",
\"result\": \"ok\",
}
award\_achievement
~~~~~~~~~~~~~~~~~~
Modifies the progress of a Game Center achievement.
Parameters
^^^^^^^^^^
Takes a Dictionary as a parameter, with 3 fields:
- ``name`` (string) the achievement name
- ``progress`` (float) the achievement progress from 0.0 to 100.0
(passed to ``GKAchievement::percentComplete``)
- ``show_completion_banner`` (bool) whether Game Center should display
an achievement banner at the top of the screen
Example:
::
var result = award_achievement( { \"name\": \"hard_mode_completed\", \"progress\": 6.1 } )
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
On error:
::
{
\"type\": \"award_achievement\",
\"result\": \"error\",
\"error_code\": the error code taken from NSError::code,
}
On success:
::
{
\"type\": \"award_achievement\",
\"result\": \"ok\",
}
reset\_achievements
~~~~~~~~~~~~~~~~~~~
Clears all Game Center achievements. The function takes no parameters.
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
On error:
::
{
\"type\": \"reset_achievements\",
\"result\": \"error\",
\"error_code\": the value from NSError::code
}
On success:
::
{
\"type\": \"reset_achievements\",
\"result\": \"ok\",
}
request\_achievements
~~~~~~~~~~~~~~~~~~~~~
Request all the Game Center achievements the player has made progress
on. The function takes no parameters.
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
On error:
::
{
\"type\": \"achievements\",
\"result\": \"error\",
\"error_code\": the value from NSError::code
}
On success:
::
{
\"type\": \"achievements\",
\"result\": \"ok\",
\"names\": [ list of the name of each achievement ],
\"progress\": [ list of the progress made on each achievement ]
}
request\_achievement\_descriptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Request the descriptions of all existing Game Center achievements
regardless of progress. The function takes no parameters.
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
On error:
::
{
\"type\": \"achievement_descriptions\",
\"result\": \"error\",
\"error_code\": the value from NSError::code
}
On success:
::
{
\"type\": \"achievement_descriptions\",
\"result\": \"ok\",
\"names\": [ list of the name of each achievement ],
\"titles\": [ list of the title of each achievement ]
\"unachieved_descriptions\": [ list of the description of each achievement when it is unachieved ]
\"achieved_descriptions\": [ list of the description of each achievement when it is achieved ]
\"maximum_points\": [ list of the points earned by completing each achievement ]
\"hidden\": [ list of booleans indicating whether each achievement is initially visible ]
\"replayable\": [ list of booleans indicating whether each achievement can be earned more than once ]
}
show\_game\_center
~~~~~~~~~~~~~~~~~~
Displays the built in Game Center overlay showing leaderboards,
achievements, and challenges.
Parameters
^^^^^^^^^^
Takes a Dictionary as a parameter, with 2 fields:
- ``view`` (string) (optional) the name of the view to present. Accepts
\\"default\\", \\"leaderboards\\", \\"achievements\\", or
\\"challenges\\". Defaults to \\"default\\".
- ``leaderboard_name`` (string) (optional) the name of the leaderboard
to present. Only used when \\"view\\" is \\"leaderboards\\" (or
\\"default\\" is configured to show leaderboards). If not specified,
Game Center will display the aggregate leaderboard.
Examples:
::
var result = show_game_center( { \"view\": \"leaderboards\", \"leaderboard_name\": \"best_time_leaderboard\" } )
var result = show_game_center( { \"view\": \"achievements\" } )
Response event
^^^^^^^^^^^^^^
The response event will be a dictionary with the following fields:
On close:
::
{
\"type\": \"show_game_center\",
\"result\": \"ok\",
}
Multi-platform games
--------------------
When working on a multi-platform game, you won't always have the
\\"GameCenter\\" singleton available (for example when running on PC or
Android). Because the gdscript compiler looks up the singletons at
compile time, you can't just query the singletons to see and use what
you need inside a conditional block, you need to also define them as
valid identifiers (local variable or class member). This is an example
of how to work around this in a class:
| <pre class=\\"python\\">
| var GameCenter = null # define it as a class member
| func post\_score(p\_score):
| if GameCenter == null:
| return
| GameCenter.post\_score( { \\\ `value\\ <>`__ p\_score,
\\\ `category\\ <>`__ \\"my\_leaderboard\\" } )
| func check\_events():
| while GameCenter.get\_pending\_event\_count() > 0:
| # do something with events here
| pass
| func \_ready():
| # check if the singleton exists
| if Globals.has\_singleton(\\"GameCenter\\"):
| GameCenter = Globals.get\_singleton(\\"GameCenter\\")
| # connect your timer here to the \\"check\_events\\" function
.. raw:: html
</pre>

60
advanced_topics/variant_class.rst Normal file
View File

@@ -0,0 +1,60 @@
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
it's 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 it's functions through variants)
- Be used to defer calls or move data between threads.
- Be serialized as binary and stored to disk, or transfered 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/okamstudio/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 Nutex should be created to lock if multi thread access is
desired.
References:
~~~~~~~~~~~
- \\\ `core/dictionary.h\\ <https://github.com/okamstudio/godot/blob/master/core/dictionary.h>`__
- \\\ `core/array.h\\ <https://github.com/okamstudio/godot/blob/master/core/array.h>`__

8
asset_pipeline/general.rst Normal file
View File

@@ -0,0 +1,8 @@
General
=======
.. toctree::
:maxdepth: 1
:name: general
managing_image_files

8
asset_pipeline/index.rst Normal file
View File

@@ -0,0 +1,8 @@
Asset pipeline
==============
.. toctree::
:maxdepth: 2
:name: asset-pipeline
general

113
asset_pipeline/managing_image_files.rst Normal file
View File

@@ -0,0 +1,113 @@
Managing image files
====================
If you have read the previous tutorials on [[Resources]] and [[File
System]], at this point you know that regular image files (.png, .jpg,
etc) are treated as regular resources in Godot.
Unlike texture resources (.tex files), image files contain no extra
information on tiling (texture repeat), mipamps or filtering. Editing
this information and saving the texture back will have not any effect,
since such formats can't contain that information.
Image loader
------------
Loading of images is done by the image loader. The behavior of the
loader for all image files can be changed in the Project Settings dialog
(Scene -> Project Settings). There is a section with values that
correspond to the every image file when loaded:
.. image:: /img/imgloader.png
Image loader options
--------------------
Filter
~~~~~~
Filter is used when the image is stretched more than it's original size,
so a texel in the image is bigger than a pixel on the screen. Turning
off the fiter produces a retro-like look:
.. image:: /img/imagefilter.png
Repeat
~~~~~~
Repeat is mainly used for 3D textures, so it's off by default (textures
are imported with the scenes and usually are not in the project as image
files). When using UV coordinates (something not as common in 2D), and
the UV value goes beyond the 0,0,1,1 rect, the texture repeats instead
of clamping to the edge.
Mipmaps
~~~~~~~
When the mipmaps option is enabled, Godot will generate mip-maps.
Mipmaps are versions of the image shrunk by half in both axis,
recursively, until the image is 1 pixel of size. When the 3D hardware
needs to shrink the image, it finds the largest mipmap it can scale
from, and scales from there. This improves performance and image
quality.
.. image:: /img/mipmaps.png
When Mip-Maps are disabled, images start distorting badly when shrunk
excessively:
.. image:: /img/imagemipmap.png
Alpha blending
~~~~~~~~~~~~~~
The \\\ `blending
equation\\ <http://en.wikipedia.org/wiki/Alpha_compositing>`__ used by
applications like Photoshop is too complex for real-time. There are
better approximations such as \\\ `pre-multiplied
alpha\\ <http://blogs.msdn.com/b/shawnhar/archive/2009/11/06/premultiplied-alpha.aspx?Redirected=true>`__,
but they impose more stress in the asset pipeline. In the end, we are
left with textures that have artifacts in the edges, because apps such
as Photoshop store white pixels in completely transparent areas. Such
white pixels end up showing thanks to the texture filter (when active).
Godot has an option to fix the edges of the image (by painting invisible
pixels the same color as the visible neighbours):
.. image:: /img/fixedborder.png
To do this, open the image from the resources tab, or edit it from the
property editor from another node or resource, then go to the object
options and select \\"Fix Border Alpha\\", then save it.
.. image:: /img/imagefixalpha.png
Since fixing this in so many images can be a little annoying, both
Texture Import and Image Export can also perform this operation.
Texture import
~~~~~~~~~~~~~~
Sometimes, it might be desired to change the above settings per image.
Unfortunately, the image loader settings are global. Texture flags also
can't be saved in a regular .png or .jpg file.
For such cases, the image can be imported as a texture (.tex), where the
individual flags can be changed. Godot also keeps track of the original
file and will re-import if it changes.
Importing also allows conversion to other formats (WebP, or RAM
compression) which might be of use in some cases. . More information on
the [[Importing textures]] page.
Image export
~~~~~~~~~~~~
It is also possible to convert images to other formats (WebP or RAM
compression) on export, as well as instructing the exporter to create an
Atlas for a set of images. It is also possible to ask the exporter to
scale all images (or selected groups).
More information on the [[Exporting images]] page.

82
classes/class_dictionary.rst Normal file
View File

@@ -0,0 +1,82 @@
Dictionary
==========
**Category:** Built-In Types
----------------------------
Brief Description
-----------------
Dictionary type.
Member Functions
----------------
- void **`clear <#clear>`__** **(** **)**
- `bool <class_bool>`__ **`empty <#empty>`__** **(** **)**
- void **`erase <#erase>`__** **(** var value **)**
- `bool <class_bool>`__ **`has <#has>`__** **(** var value **)**
- `int <class_int>`__ **`hash <#hash>`__** **(** **)**
- `Array <class_array>`__ **`keys <#keys>`__** **(** **)**
- `int <class_int>`__ **`parse\_json <#parse_json>`__** **(**
`String <class_string>`__ json **)**
- `int <class_int>`__ **`size <#size>`__** **(** **)**
- `String <class_string>`__ **`to\_json <#to_json>`__** **(** **)**
Description
-----------
Dictionary type. Associative container which contains values referenced
by unique keys. Dictionaries are always passed by reference.
Member Function Description
---------------------------
clear
~~~~~
- void **clear** **(** **)**
Clear the dictionary, removing all key/value pairs.
empty
~~~~~
- `bool <class_bool>`__ **empty** **(** **)**
Return true if the dictionary is empty.
erase
~~~~~
- void **erase** **(** var value **)**
Erase a dictionary key/value pair by key.
has
~~~
- `bool <class_bool>`__ **has** **(** var value **)**
Return true if the dictionary has a given key.
hash
~~~~
- `int <class_int>`__ **hash** **(** **)**
Return a hashed integer value representing the dictionary contents.
keys
~~~~
- `Array <class_array>`__ **keys** **(** **)**
Return the list of keys in the dictionary.
size
~~~~
- `int <class_int>`__ **size** **(** **)**
Return the size of the dictionary (in pairs).

251
conf.py
View File

@@ -1,258 +1,67 @@
# -*- coding: utf-8 -*-
#
# Godot Engine documentation build configuration file, created by
# sphinx-quickstart on Sat Dec 12 16:57:47 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# Godot Engine documentation build configuration file
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
# Sphinx extension module names and templates location
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
# You can specify multiple suffix as a list of string: ['.rst', '.md']
source_suffix = '.rst'
source_encoding = 'utf-8-sig'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
# The master toctree document
master_doc = 'index'
# General information about the project.
project = u'Godot Engine'
copyright = u'2015, Juan Linietsky, Ariel Manzur and the Godot community'
# General information about the project
project = 'Godot Engine'
copyright = '2014-2016, Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0)'
author = 'Juan Linietsky, Ariel Manzur and the Godot community'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '2.0'
# The full version, including alpha/beta/rc tags.
release = '2.0'
# Version info for the project, acts as replacement for |version| and |release|
# The short X.Y version
version = 'latest'
# The full version, including alpha/beta/rc tags
release = 'latest'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
language = 'en'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
# Pygments (syntax highlighting) style to use
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
# Output file base name for HTML help builder
htmlhelp_basename = 'GodotEnginedoc'
# -- Options for reStructuredText parser ----------------------------------
# Enable directives that insert the contents of external files
file_insertion_enabled = False
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'GodotEngine.tex', u'Godot Engine Documentation',
u'Juan Linietsky, Ariel Manzur and the Godot community', 'manual'),
(master_doc, 'GodotEngine.tex', 'Godot Engine Documentation',
'Juan Linietsky, Ariel Manzur and the Godot community', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'godotengine', u'Godot Engine Documentation',
[u'Juan Linietsky, Ariel Manzur and the Godot community'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'GodotEngine', u'Godot Engine Documentation',
u'Juan Linietsky, Ariel Manzur and the Godot community', 'GodotEngine', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

BIN
img/andtemplates.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
img/fixedborder.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
img/imagefilter.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.2 KiB

BIN
img/imagefixalpha.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
img/imagemipmap.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

BIN
img/imgloader.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

BIN
img/lintemplates.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
img/mipmaps.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
img/wintemplates.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

25
index.rst
View File

@@ -6,17 +6,22 @@
Welcome to Godot Engine's documentation!
========================================
Contents:
The main documentation for the site is organized into a couple sections:
* :ref:`user-doc`
.. toctree::
:maxdepth: 2
:maxdepth: 3
:caption: User documentation
:name: user-doc
asset_pipeline/index
advanced_topics/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. Indices and tables
.. ------------------
..
.. * :ref:`genindex`
.. * :ref:`modindex`
.. * :ref:`search`