import_process.rst 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  1. .. _doc_import_process:
  2. Import process
  3. ==============
  4. What is it for?
  5. ---------------
  6. When Godot was created, it was probably after several failed and not so
  7. failed engine attempts (well, each attempt failed a little less.. and so
  8. on). One of the most difficult areas of creating game engines is
  9. managing the import process. That means, getting the assets that artists
  10. make into the game, in a way that functions optimally.
  11. Artists use certain tools and formats, and programmers would rather have
  12. their data into a different format. This is because artists put their
  13. focus on creating assets with the best quality possible, while
  14. programmers have to make sure they actually run at decent speed (or run
  15. at all), use a certain amount of memory, and don't take ages loading
  16. from disk.
  17. One would think that just writing a converter/importer would be enough,
  18. but this is not all there is to it. The same way programmers iterate
  19. several times over their code, artists keep making changes to their
  20. assets. This generates some bottleneck, because *someone* has to keep
  21. re-importing that artwork right? And importing assets is often something
  22. that has to be agreed by both parties, as the programmer needs to decide
  23. how the artwork is imported and the artists needs to see how it looks.
  24. The goal to establishing an import process is that both can agree on how
  25. the rules under which the assets are going to be imported the first
  26. time, and the system will apply those rules automatically each time the
  27. asset is re-imported.
  28. Godot does not do the re-import process automatically, though. It gives
  29. the team the option to do it at any time ( a red icon on the top right
  30. of the screen, allows the ability to do it at any desired time).
  31. Does it always work?
  32. --------------------
  33. The aim of the import system is that it works well enough for most
  34. common cases and projects. What is there has been tested and seems to
  35. cover most needs.
  36. However, as mentioned before, this is on of the most difficult areas of
  37. writing a game engine. It may happen often (specially on large projects,
  38. ports, or projects with unusual requirement) that what is provided is
  39. not enough. It's easy to say that the engine is open source and that the
  40. programmer should make their own if they don't like what is there, but
  41. that would be making a huge disservice to the users and not the right
  42. attitude. Because of that, we made sure to provide as many tools and
  43. helpers as possible to support a custom import process, for example:
  44. - Access to the internals of almost all data structures is provided to
  45. the scripting and C++ API, as well as saving and loading in all
  46. supported file formats.
  47. - Some importers (like the 3D asset importer) support scripts to modify
  48. the data being imported.
  49. - Support for creating custom import plugins is also provided, even for
  50. replacing the existing ones.
  51. - If all else fails, Godot supports for adding custom resource loaders,
  52. to load data in alternative formats, without intermediate conversion.
  53. Both the import system and the custom tools provided will improve over
  54. time as more use cases are revealed to us.
  55. Importing assets
  56. ----------------
  57. Source asset location
  58. ~~~~~~~~~~~~~~~~~~~~~
  59. To begin, it is a good idea to define where the original assets created
  60. by the artists (before they are imported) will be located. Normally,
  61. Godot does not mind much about the location, but if the project has
  62. several developers, it is a good idea to understand the simple rule for
  63. it to work for everyone.
  64. First of all, it would be really good for this location to **not** be
  65. inside the project path (where engine.cfg is located, or any
  66. sub-folder). Godot expects regular resources in there, and may consider
  67. many of the files used as source art as regular resources. This would
  68. lead to it bundling all of them when the project is exported, something
  69. which is undesired.
  70. Now that it is clear that this location must be outside the project
  71. folder, the rule that Godot uses to reference external assets can be
  72. explained. When an asset is imported, the engine stores a relative path
  73. from the project path to the asset (In windows, this works as long as
  74. they are on the same drive, otherwise an absolute path is stored). This
  75. ensures that the same asset can be re-imported in another computer.
  76. The usual approach to this, when using a VCS such as Subversion,
  77. Perforce or GIT, is to create the project in a subfolder, so both it and
  78. the source assets can be committed to a same repository. For example:
  79. Repository layout:
  80. ::
  81. source_assets/sfx/explosion.wav
  82. source_assets/sfx/crash.wav
  83. source_assets/fonts/myfont.ttf
  84. source_assets/translation/strings.csv
  85. source_assets/art/niceart.psd
  86. game/engine.cfg
  87. In the above example, artists, musican, translators, etc. can work in
  88. the source_assets/ folder, then import the assets to the game/ folder.
  89. When the repository is updated, anyone can re-import the assets if they
  90. changed.
  91. Import dialogs
  92. ~~~~~~~~~~~~~~
  93. Godot provides for importing several types of assets, all of them can be
  94. accessed from the import dialog:
  95. .. image:: /img/import.png
  96. Each of the dialog shares a similar function, a source file (or several
  97. of them) must be provided, as well as a target destination inside the
  98. project folders. Once imported, Godot saves this information as metadata
  99. in the imported asset itself.
  100. .. image:: /img/importdialogs.png
  101. More information about each specific type of asset can be found in
  102. specific sections, such as `Importing Textures <import_textures>`__.
  103. Tracking changes and re-importing
  104. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  105. Godot tracks changes in the source assets constantly. If at least one
  106. asset has been found to be modified (md5 is different than when it was
  107. imported), a small red indicator will appear in the top right corner of
  108. the screen.
  109. .. image:: /img/changes.png
  110. From that moment onward, the user can choose to re-import at any given
  111. time by clicking on the red-icon. When this action is done, a dialog
  112. will pop-up showing which resources can be re-imported (all selected
  113. by default).
  114. Accepting that dialog will immediately re-import the resources and
  115. will update any of them currently in use in the editor (like a
  116. texture, model or audio file).
  117. .. image:: /img/changed.png
  118. Manually re-importing
  119. ~~~~~~~~~~~~~~~~~~~~~
  120. The re-import process is automatic, but it may be desired at some point
  121. to change the settings of an already imported file, so it can be
  122. re-imported differently. For this, the Import Settings window is
  123. provided.
  124. .. image:: /img/isettings.png
  125. This screen allows the user to re-open the corresponding import-window
  126. to re-import that asset again, with the ability to change any of the
  127. settings.
  128. .. image:: /img/reimported.png