222 lines
8.2 KiB
ReStructuredText
222 lines
8.2 KiB
ReStructuredText
.. _doc_exporting_projects:
|
|
|
|
Exporting projects
|
|
==================
|
|
|
|
.. highlight:: none
|
|
|
|
Why export?
|
|
-----------
|
|
|
|
Originally, Godot did not have any means to export projects. The
|
|
developers would compile the proper binaries and build the packages for
|
|
each platform manually.
|
|
|
|
When more developers (and even non-programmers) started using it, and
|
|
when our company started taking more projects at the same time, it
|
|
became evident that this was a bottleneck.
|
|
|
|
On PC
|
|
~~~~~
|
|
|
|
Distributing a game project on PC with Godot is rather easy. Drop
|
|
the Godot binary in the same directory as the ``project.godot`` file,
|
|
then compress the project directory and you are done.
|
|
|
|
It sounds simple, but there are probably a few reasons why the developer
|
|
may not want to do this. The first one is that it may not be desirable
|
|
to distribute loads of files. Some developers may not like curious users
|
|
peeking at how the game was made, others may find it inelegant, and so on.
|
|
Another reason is that the developer might prefer a specially-compiled
|
|
binary, which is smaller in size, more optimized and does not include
|
|
tools like the editor and debugger.
|
|
|
|
Finally, Godot has a simple but efficient system for
|
|
:ref:`creating DLCs as extra package files <doc_exporting_pcks>`.
|
|
|
|
On mobile
|
|
~~~~~~~~~
|
|
|
|
The same scenario on mobile platforms is a little worse.
|
|
To distribute a project on those devices, a binary for each of
|
|
those platforms is built, then added to a native project together
|
|
with the game data.
|
|
|
|
This can be troublesome because it means that the developer must be
|
|
familiarized with the SDK of each platform before even being able to
|
|
export. While learning each SDK is always encouraged, it can be
|
|
frustrating to be forced to do it at an undesired time.
|
|
|
|
There is also another problem with this approach: different devices
|
|
prefer some data in different formats to run. The main example of this
|
|
is texture compression. All PC hardware uses S3TC (BC) compression and
|
|
that has been standardized for more than a decade, but mobile devices
|
|
use different formats for texture compression, such as PVRTC (iOS) or
|
|
ETC (Android).
|
|
|
|
Export menu
|
|
-----------
|
|
|
|
After many attempts at different export workflows, the current one has
|
|
proven to work the best. At the time of this writing, not all platforms are
|
|
supported yet, but the supported platforms continue to grow.
|
|
|
|
To open the export menu, click the **Export** button:
|
|
|
|
.. image:: img/export.png
|
|
|
|
The export menu will open. However, it will be completely empty.
|
|
This is because we need to add an export preset.
|
|
|
|
.. image:: img/export_dialog.png
|
|
|
|
To create an export preset, click the **Add…** button at the top
|
|
of the export menu. This will open a drop-down list of platforms
|
|
to choose from for an export preset.
|
|
|
|
.. image:: img/export_preset.png
|
|
|
|
The default options are often enough to export, so tweaking them is
|
|
usually not necessary. However, many platforms require additional
|
|
tools (SDKs) to be installed to be able to export. Additionally, Godot
|
|
needs export templates installed to create packages. The export menu
|
|
will complain when something is missing and will not allow the user to
|
|
export for that platform until they resolve it:
|
|
|
|
.. image:: img/export_error.png
|
|
|
|
At that time, the user is expected to come back to the documentation and follow
|
|
instructions on how to properly set up that platform.
|
|
|
|
Export templates
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Apart from setting up the platform, the export templates must be
|
|
installed to be able to export projects. They can be obtained as a
|
|
TPZ file (which is a renamed ZIP archive) from the
|
|
`download page of the website <https://www.godotengine.org/download>`_.
|
|
|
|
Once downloaded, they can be installed using the **Install Export Templates**
|
|
option in the editor:
|
|
|
|
.. image:: img/exptemp.png
|
|
|
|
.. _doc_exporting_projects_export_mode:
|
|
|
|
Resource options
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
When exporting, Godot makes a list of all the files to export and then
|
|
creates the package. There are 3 different modes for exporting:
|
|
|
|
- Export all resources in the project
|
|
- Export selected scenes (and dependencies)
|
|
- Export selected resources (and dependencies)
|
|
|
|
.. image:: img/expres.png
|
|
|
|
**Export all resources in the project** will export every resource in the
|
|
project. **Export selected scenes** and **Export selected resources** gives
|
|
you a list of the scenes or resources in the project, and you have to
|
|
select every scene or resource you want to export.
|
|
|
|
.. image:: img/expselected.png
|
|
|
|
.. note::
|
|
|
|
Files and folders whose name begin with a period will never be included in
|
|
the exported project. This is done to prevent version control folders like
|
|
``.git`` from being included in the exported PCK file.
|
|
|
|
Below the list of resources are two filters that can be setup. The first allows
|
|
non resource files such as ``.txt``,``.json`` and ``.csv`` to be exported with
|
|
the project. The second filter can be used to exclude every file of a certain
|
|
type without manually deselecting every one. For example, ``.png`` files.
|
|
|
|
Exporting from the command line
|
|
-------------------------------
|
|
|
|
In production, it is useful to automate builds, and Godot supports this
|
|
with the ``--export`` and ``--export-debug`` command line parameters.
|
|
Exporting from the command line still requires an export preset to define
|
|
the export parameters. A basic invocation of the command would be:
|
|
|
|
.. code-block:: shell
|
|
|
|
godot --export "Windows Desktop" some_name.exe
|
|
|
|
This will export to ``some_name.exe``, assuming there is a preset
|
|
called "Windows Desktop" and the template can be found. (The export preset name
|
|
must be written within quotes if it contains spaces or special characters.)
|
|
The output path is *relative to the project path* or *absolute*;
|
|
**it does not respect the directory the command was invoked from**.
|
|
|
|
The output file extension should match the one used by the Godot export process:
|
|
|
|
- Windows: ``.exe``
|
|
- macOS: ``.zip`` (from all platforms) or ``.dmg`` (only when exporting *from* macOS).
|
|
``.app`` is not supported directly, although the generated ZIP archive contains an ``.app`` bundle.
|
|
- Linux: Any extension (including none). ``.x86_64`` is typically used for 64-bit x86 binaries.
|
|
- HTML5: ``.zip``
|
|
- Android: ``.apk``
|
|
- iOS: ``.zip``
|
|
|
|
You can also configure it to export *only* the PCK or ZIP file, allowing
|
|
a single exported main pack file to be used with multiple Godot executables.
|
|
When doing so, the export preset name must still be specified on the command line:
|
|
|
|
.. code-block:: shell
|
|
|
|
godot --export-pack "Windows Desktop" some_name.pck
|
|
|
|
It is often useful to combine the ``--export`` flag with the ``--path``
|
|
flag, so that you do not need to ``cd`` to the project folder before running
|
|
the command:
|
|
|
|
.. code-block:: shell
|
|
|
|
godot --path /path/to/project --export "Windows Desktop" some_name.exe
|
|
|
|
.. seealso::
|
|
|
|
See :ref:`doc_command_line_tutorial` for more information about using Godot
|
|
from the command line.
|
|
|
|
PCK versus ZIP pack file formats
|
|
--------------------------------
|
|
|
|
Each format has its upsides and downsides. PCK is the default and recommended
|
|
format for most use cases, but you may want to use a ZIP archive instead
|
|
depending on your needs.
|
|
|
|
**PCK format:**
|
|
|
|
- Uncompressed format. Larger file size, but faster to read/write.
|
|
- Not readable and writable using tools normally present on the user's
|
|
operating system, even though there are
|
|
`third-party tools <https://github.com/hhyyrylainen/GodotPckTool>`__
|
|
to extract and create PCK files.
|
|
|
|
**ZIP format:**
|
|
|
|
- Compressed format. Smaller file size, but slower to read/write.
|
|
- Readable and writable using tools normally present on the user's operating system.
|
|
This can be useful to make modding easier (see also :ref:`doc_exporting_pcks`).
|
|
|
|
.. warning::
|
|
|
|
Due to a `known bug <https://github.com/godotengine/godot/pull/42123>`__,
|
|
when using a ZIP file as a pack file, the exported binary will not try to use
|
|
it automatically. Therefore, you have to create a *launcher script* that
|
|
the player can double-click or run from a terminal to launch the project::
|
|
|
|
:: launch.bat (Windows)
|
|
@echo off
|
|
my_project.exe --main-pack my_project.zip
|
|
|
|
# launch.sh (Linux)
|
|
./my_project.x86_64 --main-pack my_project.zip
|
|
|
|
Save the launcher script and place it in the same folder as the exported binary.
|
|
On Linux, make sure to give executable permissions to the launcher script using
|
|
the command ``chmod +x launch.sh``.
|