diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..69fa449dd --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/Makefile b/Makefile index 7f5477bf7..09cdd26ac 100644 --- a/Makefile +++ b/Makefile @@ -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 ' where 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 diff --git a/README.md b/README.md new file mode 100644 index 000000000..9612cceb1 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# Godot Engine documentation + +This repository contains the source files of Godot Engine's documentation. diff --git a/advanced_topics/batch_building_templates.rst b/advanced_topics/batch_building_templates.rst new file mode 100644 index 000000000..7ed021c46 --- /dev/null +++ b/advanced_topics/batch_building_templates.rst @@ -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 ../../.. diff --git a/advanced_topics/binary_serialization_api.rst b/advanced_topics/binary_serialization_api.rst new file mode 100644 index 000000000..b815dd63f --- /dev/null +++ b/advanced_topics/binary_serialization_api.rst @@ -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&0x80000000!=0 and NameCount=val&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&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&0x7FFFFFFF = elements, val&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&0x7FFFFFFF = elements, val&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 | | | | ++--------------------------------------------+-------+-----------+----------------+ diff --git a/advanced_topics/changing_editor_fonts.rst b/advanced_topics/changing_editor_fonts.rst new file mode 100644 index 000000000..4c02176d1 --- /dev/null +++ b/advanced_topics/changing_editor_fonts.rst @@ -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. diff --git a/advanced_topics/command_line_tutorial.rst b/advanced_topics/command_line_tutorial.rst new file mode 100644 index 000000000..319eae0bb --- /dev/null +++ b/advanced_topics/command_line_tutorial.rst @@ -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: + +| 
+| #sayhello.gd
+| extends SceneTree
+
+| func \_init():
+| print(\\"Hello!\\")
+| quit()
+
+.. raw:: html
+
+
+ +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). diff --git a/advanced_topics/compiling.rst b/advanced_topics/compiling.rst new file mode 100644 index 000000000..bbf10580d --- /dev/null +++ b/advanced_topics/compiling.rst @@ -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 diff --git a/advanced_topics/compiling_for_android.rst b/advanced_topics/compiling_for_android.rst new file mode 100644 index 000000000..423d470ba --- /dev/null +++ b/advanced_topics/compiling_for_android.rst @@ -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. + + diff --git a/advanced_topics/compiling_for_ios.rst b/advanced_topics/compiling_for_ios.rst new file mode 100644 index 000000000..9de156943 --- /dev/null +++ b/advanced_topics/compiling_for_ios.rst @@ -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. diff --git a/advanced_topics/compiling_for_linux.rst b/advanced_topics/compiling_for_linux.rst new file mode 100644 index 000000000..89512ffcf --- /dev/null +++ b/advanced_topics/compiling_for_linux.rst @@ -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. + + diff --git a/advanced_topics/compiling_for_osx.rst b/advanced_topics/compiling_for_osx.rst new file mode 100644 index 000000000..1a5f307aa --- /dev/null +++ b/advanced_topics/compiling_for_osx.rst @@ -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\\ `__ 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 diff --git a/advanced_topics/compiling_for_universal_windows_apps.rst b/advanced_topics/compiling_for_universal_windows_apps.rst new file mode 100644 index 000000000..687ed0b50 --- /dev/null +++ b/advanced_topics/compiling_for_universal_windows_apps.rst @@ -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\\ `__. +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\\ `__ +- There are 2 command line tools that might be useful, \\\ `App + Packager\\ `__ + and + \\\ `SignTool\\ `__. +- There are a bunch of tools on \\"powershell\\" that deal with + packages that might be relevant: + \\\ `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). diff --git a/advanced_topics/compiling_for_windows.rst b/advanced_topics/compiling_for_windows.rst new file mode 100644 index 000000000..e24fa89a7 --- /dev/null +++ b/advanced_topics/compiling_for_windows.rst @@ -0,0 +1,151 @@ +Compiling for Windows +===================== + +Requirements +------------ + +For compiling under Windows, the following is required: + +- \\\ `Visual C++\\ `__, 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+\\ `__ + (3.0 is untested as of now). Using the 32-bits installer is + recommended. +- \\\ `Pywin32 Python + Extension\\ `__ for parallel + builds (which increase the build speed by a great factor). +- \\\ `SCons\\ `__ build system. + +Setting up SCons +---------------- + +Python adds the interpreter (python.exe) to the path. It usually +installs in C:\\\\Python (or C:\\\\Python[Version]). SCons installs +inside the python install and provides a .bat file called +\\"scons.bat\\". The location of this file can be added to the path or +it can simply be copied to C:\\\\Python together with the interpreter +executable. + +Compiling +--------- + +Start a Visual Studio command prompt (it sets up environment variables +needed by SCons to locate the compiler and SDK), go to the root dir of +the engine source code and type: + +:: + + C:\\godot> scons 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. + + diff --git a/advanced_topics/configure_your_ide.rst b/advanced_topics/configure_your_ide.rst new file mode 100644 index 000000000..e69790f06 --- /dev/null +++ b/advanced_topics/configure_your_ide.rst @@ -0,0 +1,11 @@ +Configure an IDE +================ + +With Eclipse +------------ + +With QtCreator +-------------- + +With another editor (vim, emacs, Atom...) +----------------------------------------- diff --git a/advanced_topics/core_types.rst b/advanced_topics/core_types.rst new file mode 100644 index 000000000..2091e6d65 --- /dev/null +++ b/advanced_topics/core_types.rst @@ -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\\ `__ + +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\\ `__ +- \\\ `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\\ `__ +- \\\ `core/list.h\\ `__ +- \\\ `core/set.h\\ `__ +- \\\ `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\\ `__ + +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\\ `__ + +Math types +---------- + +There are several linear math types available in the core/math +directory, they are basically just that. + +References: +~~~~~~~~~~~ + +- \\\ `core/math\\ `__ + +NodePath +-------- + +This is a special datatype sued for storing paths in a scenetree and +referencing them fast. + +References: +~~~~~~~~~~~ + +- \\\ `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\\ `__ diff --git a/advanced_topics/creating_android_modules.rst b/advanced_topics/creating_android_modules.rst new file mode 100644 index 000000000..e4b7549d4 --- /dev/null +++ b/advanced_topics/creating_android_modules.rst @@ -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: + +| 
+| def can\_build(plat):
+| return plat==\\"android\\"
+
+.. raw:: html
+
+
+ +If more than one platform can be built (typical if implementing the +module also for iOS), check manually for Android in the configure +functions: + +| 
+| def can\_build(plat):
+| return plat\\"android\\" or plat\\"iphone\\"
+
+| def configure(env):
+| if env['platform'] == 'android':
+| #androd specific code
+
+.. raw:: html
+
+
+ +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: + +| 
+| //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
+
+
+ +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: + +
GodotLib.calldeferred(, \\"\\", new
+Object[]{param1,param2,etc});
+
+.. raw:: html
+
+
+ +Add this singleton to the build of the project by adding the following +to config.py: + +| 
+| 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
+
+
+ +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: + +| 
+| 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
+
+
+ +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: + +| 
+| 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
+
+
+ +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\\ `__ + +Then, add the module folder to the project: + +| 
+| 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
+
+
+ +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: + +| 
+| #in any file
+
+var singleton=null
+
+| func \_init():
+| singleton = Globals.get\_singleton(\\"MySingleton\\")
+| print( singleton.myFunction(\\"Hello\\") )
+
+.. raw:: html
+
+
+ +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\\ `__. diff --git a/advanced_topics/cross-compiling_for_ios_on_linux.rst b/advanced_topics/cross-compiling_for_ios_on_linux.rst new file mode 100644 index 000000000..3be1d2cbd --- /dev/null +++ b/advanced_topics/cross-compiling_for_ios_on_linux.rst @@ -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\\ `__ +says they relaxed some of the \\\ `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**\\ `__ (a dmg image) +- \\\ `**Clang >=3.5**\\ `__ for your + development machine installed and in the ``PATH``. It needs to be + version >= 3.5 to target ``arm64`` architecture. +- \\\ `**Fuse**\\ `__ for mounting and + umounting the dmg image. +- \\\ `**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**\\ `__ + 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``. diff --git a/advanced_topics/custom_modules_in_c++.rst b/advanced_topics/custom_modules_in_c++.rst new file mode 100644 index 000000000..b0190a54a --- /dev/null +++ b/advanced_topics/custom_modules_in_c++.rst @@ -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: + +| 
+| /\* sumator.h \*/
+| #ifndef SUMATOR\_H
+| #define SUMATOR\_H
+
+#include "reference.h"
+
+| class Sumator : public Reference {
+| OBJ\_TYPE(Sumator,Reference);
+
+int count;
+
+| protected:
+| static void \_bind\_methods();
+| public:
+
+| void add(int value);
+| void reset();
+| int get\_total() const;
+
+| Sumator();
+| };
+
+#endif
+
+.. raw:: html
+
+
+ +And then the cpp file. + +| 
+| /\* sumator.cpp \*/
+
+#include "sumator.h"
+
+void Sumator::add(int value) {
+
+| count+=value;
+| }
+
+void Sumator::reset() {
+
+| count=0;
+| }
+
+int Sumator::get\_total() const {
+
+| return count;
+| }
+
+void Sumator::\_bind\_methods() {
+
+| ObjectTypeDB::bind\_method("add",&Sumator::add);
+| ObjectTypeDB::bind\_method("reset",&Sumator::reset);
+| ObjectTypeDB::bind\_method("get\_total",&Sumator::get\_total);
+| }
+
+| Sumator::Sumator() {
+| count=0;
+| }
+
+.. raw:: html
+
+
+ +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 + +| 
+| /\* 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
+
+
+ +| 
+| /\* register\_types.cpp \*/
+
+| #include "register\_types.h"
+| #include "object\_type\_db.h"
+| #include "sumator.h"
+
+void register\_sumator\_types() {
+
+| ObjectTypeDB::register\_type<Sumator>();
+| }
+
+| void unregister\_sumator\_types() {
+| //nothing to do here
+| }
+
+.. raw:: html
+
+
+ +Next, we need to create a SCsub so the build system compiles this +module: + +
+
+#. SCsub
+   Import('env')
+
+env.add\_source\_files(env.modules\_sources,"\*.cpp") # just add
+all cpp files to the build
+
+.. raw:: html
+
+
+ +And finally, the configuration file for the module, this is a simple +python script that must be named 'config.py' + +
+
+#. config.py
+
+| def can\_build(platform):
+| return True
+
+| def configure(env):
+| pass
+
+.. raw:: html
+
+
+ +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: + +| 
+| var s = Sumator.new()
+| s.add(10)
+| s.add(20)
+| s.add(30)
+| print( s.get\_total() )
+| s.reset()
+
+.. raw:: html
+
+
+ +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. diff --git a/advanced_topics/developing.rst b/advanced_topics/developing.rst new file mode 100644 index 000000000..757ab1edd --- /dev/null +++ b/advanced_topics/developing.rst @@ -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 diff --git a/advanced_topics/formats.rst b/advanced_topics/formats.rst new file mode 100644 index 000000000..38a52f5c7 --- /dev/null +++ b/advanced_topics/formats.rst @@ -0,0 +1,8 @@ +Data and file formats +===================== + +.. toctree:: + :maxdepth: 1 + :name: data-and-file-formats + + binary_serialization_api diff --git a/advanced_topics/index.rst b/advanced_topics/index.rst new file mode 100644 index 000000000..51ef88f08 --- /dev/null +++ b/advanced_topics/index.rst @@ -0,0 +1,11 @@ +Advanced topics +=============== + +.. toctree:: + :maxdepth: 2 + :name: advanced-topics + + compiling + developing + formats + misc diff --git a/advanced_topics/introduction_to_godot_development.rst b/advanced_topics/introduction_to_godot_development.rst new file mode 100644 index 000000000..1183a3290 --- /dev/null +++ b/advanced_topics/introduction_to_godot_development.rst @@ -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. diff --git a/advanced_topics/introduction_to_the_buildsystem.rst b/advanced_topics/introduction_to_the_buildsystem.rst new file mode 100644 index 000000000..1252dd3a5 --- /dev/null +++ b/advanced_topics/introduction_to_the_buildsystem.rst @@ -0,0 +1,218 @@ +Introduction to the buildsystem +=============================== + +Scons +----- + +Godot uses \\\ `Scons\\ `__ 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= + 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. diff --git a/advanced_topics/misc.rst b/advanced_topics/misc.rst new file mode 100644 index 000000000..f31ed3468 --- /dev/null +++ b/advanced_topics/misc.rst @@ -0,0 +1,11 @@ +Misc +==== + +.. toctree:: + :maxdepth: 1 + :name: misc + + command_line_tutorial + changing_editor_fonts + services_for_ios + diff --git a/advanced_topics/object_class.rst b/advanced_topics/object_class.rst new file mode 100644 index 000000000..ac84e3410 --- /dev/null +++ b/advanced_topics/object_class.rst @@ -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. + +| 
+| class CustomObject : public Object {
+
+| OBJ\_TYPE(CustomObject,Object); // this required to inherit
+| };
+
+.. raw:: html
+
+
+ +This makes objects gain a lot of functionality, like for example + +| 
+| obj = memnew(CustomObject);
+| print\_line("Object Type: ",obj->get\_type()); //print object type
+
+obj2 = obj->cast\_to<OtherType>(); // converting between types,
+this also works without RTTI enabled.
+
+.. raw:: html
+
+
+ +References: +~~~~~~~~~~~ + +- \\\ `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: + +
ObjectTypeDB::register\_type()
+
+.. raw:: html
+
+
+ +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. + +
ObjectTypeDB::register\_virtual\_type()
+
+.. raw:: html
+
+
+ +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: + +
ObjectTypeDB::register\_method(\_MD (\\"methodname\\",\\"arg1name\\",\\"arg2name\\"),&MyCustethod);
+
+.. raw:: html
+
+
+ +Default values for arguments can be passed in reverse order: + +
ObjectTypeDB::register\_method(\_MD (\\"methodname\\",\\"arg1name\\",\\"arg2name\\"),&MyCustomType::method,DEFVAL (-1));
+//default argument for arg2name
+
+.. raw:: html
+
+
+ +``_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\\ `__ + +Constants +--------- + +Classes often have enums such as: + +| 
+| enum SomeMode {
+| MODE\_FIRST,
+| MODE\_SECOND
+| };
+
+.. raw:: html
+
+
+ +For these to work when binding to methods, the enum must be declared +convertible to int, for this a macro is provided: + +
VARIANT\_ENUM\_CAST( MyClass::SomeMode); // now
+functions that take SomeMode can be bound.
+
+.. raw:: html
+
+
+ +The constants can also be bound inside ``_bind_methods``, by using: + +| 
+| BIND\_CONSTANT( MODE\_FIRST );
+| BIND\_CONSTANT( MODE\_SECOND );
+
+.. raw:: html
+
+
+ +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: + +
PropertyInfo(type,name,hint,hint\_string,usage\_flags)
+
+.. raw:: html
+
+
+ +For example: + +
PropertyInfo(Variant::INT,\\"amount\\",PROPERTY\_HINT\_RANGE,\\"0,49,1\\",PROPERTY\_USAGE\_EDITOR)
+
+.. raw:: html
+
+
+ +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 + +
PropertyInfo(Variant::STRING,\\"modes\\",PROPERTY\_HINT\_ENUM,\\"Enabled,Disabled,Turbo\\")
+
+.. raw:: html
+
+
+ +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: + +
ADD\_PROPERTY(
+PropertyInfo(Variant::INT,\\"amount\\"), \_SCS (\\"set\_amount\\"),
+\_SCS (\\"get\_amount\\") )
+
+.. raw:: html
+
+
+ +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). + +| 
+| 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
+
+
+ +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: + +| 
+| void somefunc(Object \*some\_obj) {
+
+| Button \* button = some\_obj->cast\_to<Button>();
+| }
+
+.. raw:: html
+
+
+ +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: + +| 
+| obj->connect(,target\_instance,target\_method)
+| //for example
+| obj->connect(\\"enter\_tree\\",this,\\"\_node\_entered\_tree\\")
+
+.. raw:: html
+
+
+ +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: + +
ADD\_SIGNAL( MethodInfo(\\"been\_killed\\") )
+
+.. raw:: html
+
+
+ +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. + +| 
+| class MyReference: public Reference {
+| OBJ\_TYPE( MyReference ,Reference);
+| };
+
+Ref myref = memnew( MyReference );
+
+.. raw:: html
+
+
+ +``myref`` is reference counted. It will be freed when no more Ref<> +templates point to it. + +References: +~~~~~~~~~~~ + +- \\\ `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\\ `__ + +Resource loading +---------------- + +Resources can be loaded with the ResourceLoader API, like this: + +
Ref res =
+ResourceLoader::load(\\"res://someresource.res\\")
+
+.. raw:: html
+
+
+ +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\\ `__ + +Resource saving +--------------- + +Saving a resource can be done with the resource saver API: + +
ResourceSaver::save(\\"res://someresource.res\\",instance)
+
+.. raw:: html
+
+
+ +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\\ `__ diff --git a/advanced_topics/services_for_ios.rst b/advanced_topics/services_for_ios.rst new file mode 100644 index 000000000..16bff54c0 --- /dev/null +++ b/advanced_topics/services_for_ios.rst @@ -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: + +| 
+| 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
+
+
+ +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: + +| 
+| 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
+
+
diff --git a/advanced_topics/variant_class.rst b/advanced_topics/variant_class.rst new file mode 100644 index 000000000..91bf6ea09 --- /dev/null +++ b/advanced_topics/variant_class.rst @@ -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\\ `__ + +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\\ `__ +- \\\ `core/array.h\\ `__ diff --git a/asset_pipeline/general.rst b/asset_pipeline/general.rst new file mode 100644 index 000000000..7c39c954d --- /dev/null +++ b/asset_pipeline/general.rst @@ -0,0 +1,8 @@ +General +======= + +.. toctree:: + :maxdepth: 1 + :name: general + + managing_image_files diff --git a/asset_pipeline/index.rst b/asset_pipeline/index.rst new file mode 100644 index 000000000..53b0fc161 --- /dev/null +++ b/asset_pipeline/index.rst @@ -0,0 +1,8 @@ +Asset pipeline +============== + +.. toctree:: + :maxdepth: 2 + :name: asset-pipeline + + general diff --git a/asset_pipeline/managing_image_files.rst b/asset_pipeline/managing_image_files.rst new file mode 100644 index 000000000..b4a2a10e3 --- /dev/null +++ b/asset_pipeline/managing_image_files.rst @@ -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\\ `__ used by +applications like Photoshop is too complex for real-time. There are +better approximations such as \\\ `pre-multiplied +alpha\\ `__, +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. + + diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst new file mode 100644 index 000000000..5979b2897 --- /dev/null +++ b/classes/class_dictionary.rst @@ -0,0 +1,82 @@ +Dictionary +========== + +**Category:** Built-In Types +---------------------------- + +Brief Description +----------------- + +Dictionary type. + +Member Functions +---------------- + +- void **`clear <#clear>`__** **(** **)** +- `bool `__ **`empty <#empty>`__** **(** **)** +- void **`erase <#erase>`__** **(** var value **)** +- `bool `__ **`has <#has>`__** **(** var value **)** +- `int `__ **`hash <#hash>`__** **(** **)** +- `Array `__ **`keys <#keys>`__** **(** **)** +- `int `__ **`parse\_json <#parse_json>`__** **(** + `String `__ json **)** +- `int `__ **`size <#size>`__** **(** **)** +- `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 `__ **empty** **(** **)** + +Return true if the dictionary is empty. + +erase +~~~~~ + +- void **erase** **(** var value **)** + +Erase a dictionary key/value pair by key. + +has +~~~ + +- `bool `__ **has** **(** var value **)** + +Return true if the dictionary has a given key. + +hash +~~~~ + +- `int `__ **hash** **(** **)** + +Return a hashed integer value representing the dictionary contents. + +keys +~~~~ + +- `Array `__ **keys** **(** **)** + +Return the list of keys in the dictionary. + +size +~~~~ + +- `int `__ **size** **(** **)** + +Return the size of the dictionary (in pairs). \ No newline at end of file diff --git a/conf.py b/conf.py index 711c54b43..81282392a 100644 --- a/conf.py +++ b/conf.py @@ -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 -# " v 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 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 diff --git a/img/andtemplates.png b/img/andtemplates.png new file mode 100644 index 000000000..50e5e4d59 Binary files /dev/null and b/img/andtemplates.png differ diff --git a/img/fixedborder.png b/img/fixedborder.png new file mode 100644 index 000000000..43a7f668f Binary files /dev/null and b/img/fixedborder.png differ diff --git a/img/imagefilter.png b/img/imagefilter.png new file mode 100644 index 000000000..b195d2059 Binary files /dev/null and b/img/imagefilter.png differ diff --git a/img/imagefixalpha.png b/img/imagefixalpha.png new file mode 100644 index 000000000..6735e9557 Binary files /dev/null and b/img/imagefixalpha.png differ diff --git a/img/imagemipmap.png b/img/imagemipmap.png new file mode 100644 index 000000000..0df9fba31 Binary files /dev/null and b/img/imagemipmap.png differ diff --git a/img/imgloader.png b/img/imgloader.png new file mode 100644 index 000000000..f1ce51a74 Binary files /dev/null and b/img/imgloader.png differ diff --git a/img/lintemplates.png b/img/lintemplates.png new file mode 100644 index 000000000..aeef57c50 Binary files /dev/null and b/img/lintemplates.png differ diff --git a/img/mipmaps.png b/img/mipmaps.png new file mode 100644 index 000000000..375eda262 Binary files /dev/null and b/img/mipmaps.png differ diff --git a/img/wintemplates.png b/img/wintemplates.png new file mode 100644 index 000000000..5df377b05 Binary files /dev/null and b/img/wintemplates.png differ diff --git a/index.rst b/index.rst index 6af9eb392..5c6b4e64d 100644 --- a/index.rst +++ b/index.rst @@ -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`