2016-02-08 23:45:57 +01:00
|
|
|
.. _doc_import_process:
|
2016-02-08 22:07:55 +01:00
|
|
|
|
2016-02-06 01:54:33 +01:00
|
|
|
Import process
|
|
|
|
==============
|
|
|
|
|
|
|
|
What is it for?
|
|
|
|
---------------
|
|
|
|
|
2017-04-23 15:09:46 +02:00
|
|
|
One of the most difficult things to get right when creating game engines
|
|
|
|
is managing the import process. That means, getting the assets that artists
|
2016-02-06 01:54:33 +01:00
|
|
|
make into the game, in a way that functions optimally.
|
|
|
|
|
|
|
|
Artists use certain tools and formats, and programmers would rather have
|
2017-04-23 15:09:46 +02:00
|
|
|
their data in a different format. This is because artists put their
|
2016-02-06 01:54:33 +01:00
|
|
|
focus on creating assets with the best quality possible, while
|
|
|
|
programmers have to make sure they actually run at decent speed (or run
|
|
|
|
at all), use a certain amount of memory, and don't take ages loading
|
|
|
|
from disk.
|
|
|
|
|
|
|
|
One would think that just writing a converter/importer would be enough,
|
|
|
|
but this is not all there is to it. The same way programmers iterate
|
|
|
|
several times over their code, artists keep making changes to their
|
2017-04-23 15:09:46 +02:00
|
|
|
assets. This generates a bottleneck, because *someone* has to keep
|
|
|
|
re-importing that artwork, right? And importing assets is often something
|
2016-02-06 01:54:33 +01:00
|
|
|
that has to be agreed by both parties, as the programmer needs to decide
|
|
|
|
how the artwork is imported and the artists needs to see how it looks.
|
|
|
|
|
|
|
|
The goal to establishing an import process is that both can agree on how
|
|
|
|
the rules under which the assets are going to be imported the first
|
|
|
|
time, and the system will apply those rules automatically each time the
|
|
|
|
asset is re-imported.
|
|
|
|
|
|
|
|
Godot does not do the re-import process automatically, though. It gives
|
2017-07-16 17:23:56 +02:00
|
|
|
the team the option to do it at any time (a red icon on the top right
|
2016-02-06 01:54:33 +01:00
|
|
|
of the screen, allows the ability to do it at any desired time).
|
|
|
|
|
|
|
|
Does it always work?
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
The aim of the import system is that it works well enough for most
|
|
|
|
common cases and projects. What is there has been tested and seems to
|
|
|
|
cover most needs.
|
|
|
|
|
2016-05-09 20:01:48 +02:00
|
|
|
However, as mentioned before, this is one of the most difficult areas of
|
2016-02-06 01:54:33 +01:00
|
|
|
writing a game engine. It may happen often (specially on large projects,
|
|
|
|
ports, or projects with unusual requirement) that what is provided is
|
|
|
|
not enough. It's easy to say that the engine is open source and that the
|
|
|
|
programmer should make their own if they don't like what is there, but
|
|
|
|
that would be making a huge disservice to the users and not the right
|
|
|
|
attitude. Because of that, we made sure to provide as many tools and
|
|
|
|
helpers as possible to support a custom import process, for example:
|
|
|
|
|
|
|
|
- Access to the internals of almost all data structures is provided to
|
|
|
|
the scripting and C++ API, as well as saving and loading in all
|
|
|
|
supported file formats.
|
|
|
|
- Some importers (like the 3D asset importer) support scripts to modify
|
|
|
|
the data being imported.
|
|
|
|
- Support for creating custom import plugins is also provided, even for
|
|
|
|
replacing the existing ones.
|
2016-05-09 20:01:48 +02:00
|
|
|
- If all else fails, Godot supports adding custom resource loaders,
|
2016-02-06 01:54:33 +01:00
|
|
|
to load data in alternative formats, without intermediate conversion.
|
|
|
|
|
|
|
|
Both the import system and the custom tools provided will improve over
|
|
|
|
time as more use cases are revealed to us.
|
|
|
|
|
|
|
|
Importing assets
|
|
|
|
----------------
|
|
|
|
|
|
|
|
Source asset location
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
To begin, it is a good idea to define where the original assets created
|
|
|
|
by the artists (before they are imported) will be located. Normally,
|
|
|
|
Godot does not mind much about the location, but if the project has
|
|
|
|
several developers, it is a good idea to understand the simple rule for
|
|
|
|
it to work for everyone.
|
|
|
|
|
|
|
|
First of all, it would be really good for this location to **not** be
|
|
|
|
inside the project path (where engine.cfg is located, or any
|
|
|
|
sub-folder). Godot expects regular resources in there, and may consider
|
|
|
|
many of the files used as source art as regular resources. This would
|
|
|
|
lead to it bundling all of them when the project is exported, something
|
|
|
|
which is undesired.
|
|
|
|
|
|
|
|
Now that it is clear that this location must be outside the project
|
|
|
|
folder, the rule that Godot uses to reference external assets can be
|
|
|
|
explained. When an asset is imported, the engine stores a relative path
|
|
|
|
from the project path to the asset (In windows, this works as long as
|
|
|
|
they are on the same drive, otherwise an absolute path is stored). This
|
|
|
|
ensures that the same asset can be re-imported in another computer.
|
|
|
|
|
2017-04-23 15:09:46 +02:00
|
|
|
The usual approach to this, when using a VCS such as Git, Mercurial or
|
|
|
|
Subversion, is to create the project in a subfolder, so both the game's
|
|
|
|
project files and the source assets can be committed to a same repository.
|
|
|
|
For example, the repository layout can look like this:
|
2016-02-06 01:54:33 +01:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
source_assets/sfx/explosion.wav
|
|
|
|
source_assets/sfx/crash.wav
|
|
|
|
source_assets/fonts/myfont.ttf
|
|
|
|
source_assets/translation/strings.csv
|
|
|
|
source_assets/art/niceart.psd
|
2017-07-16 17:23:56 +02:00
|
|
|
game/project.godot
|
2016-02-06 01:54:33 +01:00
|
|
|
|
2016-05-09 20:01:48 +02:00
|
|
|
In the above example, artists, musician, translators, etc. can work in
|
2016-02-10 18:57:06 +01:00
|
|
|
the source_assets/ folder, then import the assets to the game/ folder.
|
2016-02-06 01:54:33 +01:00
|
|
|
When the repository is updated, anyone can re-import the assets if they
|
|
|
|
changed.
|
|
|
|
|
|
|
|
Import dialogs
|
|
|
|
~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
Godot provides for importing several types of assets, all of them can be
|
|
|
|
accessed from the import dialog:
|
|
|
|
|
|
|
|
.. image:: /img/import.png
|
|
|
|
|
2017-04-23 15:09:46 +02:00
|
|
|
Each of the dialogs shares a similar function, a source file (or several
|
2016-02-06 01:54:33 +01:00
|
|
|
of them) must be provided, as well as a target destination inside the
|
|
|
|
project folders. Once imported, Godot saves this information as metadata
|
|
|
|
in the imported asset itself.
|
|
|
|
|
|
|
|
.. image:: /img/importdialogs.png
|
|
|
|
|
|
|
|
More information about each specific type of asset can be found in
|
|
|
|
specific sections, such as `Importing Textures <import_textures>`__.
|
|
|
|
|
|
|
|
Tracking changes and re-importing
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
Godot tracks changes in the source assets constantly. If at least one
|
|
|
|
asset has been found to be modified (md5 is different than when it was
|
|
|
|
imported), a small red indicator will appear in the top right corner of
|
|
|
|
the screen.
|
|
|
|
|
|
|
|
.. image:: /img/changes.png
|
|
|
|
|
2016-02-09 23:40:35 +01:00
|
|
|
From that moment onward, the user can choose to re-import at any given
|
|
|
|
time by clicking on the red-icon. When this action is done, a dialog
|
|
|
|
will pop-up showing which resources can be re-imported (all selected
|
|
|
|
by default).
|
|
|
|
|
|
|
|
Accepting that dialog will immediately re-import the resources and
|
|
|
|
will update any of them currently in use in the editor (like a
|
|
|
|
texture, model or audio file).
|
2016-02-06 01:54:33 +01:00
|
|
|
|
|
|
|
.. image:: /img/changed.png
|
|
|
|
|
|
|
|
Manually re-importing
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
The re-import process is automatic, but it may be desired at some point
|
|
|
|
to change the settings of an already imported file, so it can be
|
|
|
|
re-imported differently. For this, the Import Settings window is
|
|
|
|
provided.
|
|
|
|
|
|
|
|
.. image:: /img/isettings.png
|
|
|
|
|
|
|
|
This screen allows the user to re-open the corresponding import-window
|
|
|
|
to re-import that asset again, with the ability to change any of the
|
|
|
|
settings.
|
|
|
|
|
|
|
|
.. image:: /img/reimported.png
|