importing_scenes.rst 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508
  1. .. _doc_importing_3d_scenes:
  2. Importing 3D scenes
  3. ===================
  4. Godot scene importer
  5. --------------------
  6. When dealing with 3D assets, Godot has a flexible and configurable importer.
  7. Godot works with *scenes*. This means that the entire scene being worked on in your favorite 3D DCC will be
  8. transferred as close as possible.
  9. Godot supports the following 3D *scene file formats*:
  10. * glTF 2.0 **(recommended)**. Godot has full support for both text (``.gltf``) and binary (``.glb``) formats.
  11. * DAE (COLLADA), an older format that is fully supported.
  12. * OBJ (Wavefront) format + their MTL material files. This is also fully supported, but pretty limited (no support for pivots, skeletons, animations, PBR materials, ...).
  13. * ESCN, a Godot-specific format that Blender can export with a plugin.
  14. * FBX, supported via a reverse engineered importer. So we recommend using other formats listed above, if suitable
  15. for your workflow.
  16. Just copy the scene file together with the texture to the project repository, and Godot will do a full import.
  17. It is important that the mesh is not deformed by bones when exporting. Make sure that the skeleton is reset to its T-pose
  18. or default rest pose before exporting with your favorite 3D editor.
  19. Exporting glTF 2.0 files from Blender
  20. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  21. There are three ways to export glTF files from Blender. As a glTF binary (``.glb`` file), glTF embedded (``.gltf`` file),
  22. and with textures (``gltf`` + ``.bin`` + textures).
  23. glTF binary files are the smallest of the three options. They include the mesh and textures set up in Blender.
  24. When brought into Godot the textures are part of the object's material file.
  25. glTF embedded files function the same way as binary files. They don't provide extra functionality in Godot,
  26. and shouldn't be used since they have a larger file size.
  27. There are two reasons to use glTF with the textures separate. One is to have the scene description in a
  28. text based format and the binary data in a separate binary file. This can be useful for version control if you want to review
  29. changes in a text based format. The second is you need the texture files separate from the material file. If you don't need
  30. either of those glTF binary files are fine.
  31. .. note::
  32. Blender does not export emissive textures with the glTF file. If your model
  33. uses one, it must be brought in separately.
  34. By default, Blender has backface culling disabled on materials and will
  35. export materials to match how they render in Blender. This means that
  36. materials in Godot will have their cull mode set to **Disabled**. This can
  37. decrease performance since backfaces will be rendered, even when they are
  38. being culled by other faces. To resolve this, enable **Backface Culling** in
  39. Blender's Materials tab, then export the scene to glTF again.
  40. Exporting DAE files from Blender
  41. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  42. Blender has built-in COLLADA support, but it does not work properly for the needs of game engines
  43. and should not be used as is.
  44. Godot provides a `Blender plugin <https://github.com/godotengine/collada-exporter>`_
  45. that will correctly export COLLADA scenes for use in Godot. It does not work in Blender 2.8 or
  46. newer, but there are plans to update it in the future.
  47. Exporting ESCN files from Blender
  48. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  49. The most powerful one, called `godot-blender-exporter
  50. <https://github.com/godotengine/godot-blender-exporter>`__.
  51. It uses a .escn file, which is kind of another name for a .tscn file (Godot scene file);
  52. it keeps as much information as possible from a Blender scene. However, it is considered
  53. experimental.
  54. The ESCN exporter has a detailed `document <escn_exporter/index.html>`__ describing
  55. its functionality and usage.
  56. Exporting textures separately
  57. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58. While textures can be exported with a model in certain file formats, such as glTF 2.0, you can also export them
  59. separately. Godot uses PBR (physically based rendering) for its materials, so if a texturing program can export PBR
  60. textures they can work in Godot. This includes the `Substance suite <https://www.substance3d.com/>`__,
  61. `ArmorPaint (open source) <https://armorpaint.org/>`__, and `Material Maker (open source) <https://github.com/RodZill4/material-maker>`__.
  62. .. note:: For more information on Godot's materials, see :ref:`doc_standard_material_3d`.
  63. Exporting considerations
  64. ~~~~~~~~~~~~~~~~~~~~~~~~
  65. Since GPUs can only render triangles, meshes that contain quads or N-gons have
  66. to be *triangulated* before they can be rendered. Godot can triangulate meshes
  67. on import, but results may be unpredictable or incorrect, especially with
  68. N-gons. Regardless of the target application, triangulating *before* exporting
  69. the scene will lead to more consistent results and should be done whenever
  70. possible.
  71. To avoid issues with incorrect triangulation after importing in Godot, it is
  72. recommended to make the 3D DCC triangulate objects on its own. In Blender, this
  73. can be done by adding a Triangulate modifier to your objects and making sure
  74. **Apply Modifiers** is checked in the export dialog. Alternatively, depending on
  75. the exporter, you may be able to find and enable a **Triangulate Faces** option
  76. in the export dialog.
  77. To avoid issues with 3D selection in the editor, it is recommended to apply the
  78. object transform in the 3D DCC before exporting the scene.
  79. Import workflows
  80. ----------------
  81. Godot scene importer allows different workflows regarding how data is imported. Depending on many options, it is possible to
  82. import a scene with:
  83. * External materials (default): Where each material is saved to a file resource. Modifications to them are kept.
  84. * External meshes: Where each mesh is saved to a different file. Many users prefer to deal with meshes directly.
  85. * External animations: Allowing saved animations to be modified and merged when sources change.
  86. * External scenes: Save each of the root nodes of the imported scenes as a separate scene.
  87. * Single scene: A single scene file with everything built in.
  88. .. image:: img/scene_import1.png
  89. As different developers have different needs, this import process is highly customizable.
  90. Import options
  91. --------------
  92. The importer has several options, which will be discussed below:
  93. .. image:: img/scene_import2.png
  94. Nodes
  95. ~~~~~
  96. Root Type
  97. ^^^^^^^^^
  98. By default, the type of the root node in imported scenes is "Spatial", but this can be modified.
  99. Root Name
  100. ^^^^^^^^^
  101. Allows setting a specific name to the generated root node.
  102. Root Scale
  103. ^^^^^^^^^^
  104. The scale of the root node.
  105. Custom Script
  106. ^^^^^^^^^^^^^
  107. A special script to process the whole scene after import can be provided.
  108. This is great for post processing, changing materials, doing funny stuff
  109. with the geometry etc.
  110. Create a script like this:
  111. ::
  112. tool # Needed so it runs in the editor.
  113. extends EditorScenePostImport
  114. func post_import(scene):
  115. # Do your stuff here.
  116. return scene # remember to return the imported scene
  117. The ``post_import`` function takes the imported scene as argument (the
  118. parameter is actually the root node of the scene). The scene that
  119. will finally be used must be returned. It can be a different one.
  120. Storage
  121. ^^^^^^^
  122. By default, Godot imports a single scene. This option allows specifying
  123. that nodes below the root will each be a separate scene and instanced
  124. into the imported one.
  125. Of course, instancing such imported scenes in other places manually works, too.
  126. Materials
  127. ~~~~~~~~~
  128. Location
  129. ^^^^^^^^
  130. Godot supports materials in meshes or nodes. By default, materials will be put
  131. on each node.
  132. Storage
  133. ^^^^^^^
  134. Materials can be stored within the scene or in external files. By default,
  135. they are stored in external files so editing them is possible. This is because
  136. most 3D DCCs don't have the same material options as those present in Godot.
  137. When materials are built-in, they will be lost each time the source scene
  138. is modified and re-imported.
  139. .. note::
  140. Godot will not reimport materials that are stored in external files unless
  141. you remove the associated ``.material`` file before reimporting.
  142. To force reimporting materials every time the 3D scene is reimported, change
  143. the material storage mode in the 3D scene by selecting it in the FileSystem
  144. dock, going to the Import dock then setting **Material > Storage** to
  145. **Built-In** instead of **Files**.
  146. Keep On Reimport
  147. ^^^^^^^^^^^^^^^^
  148. Once materials are edited to use Godot features, the importer will keep the
  149. edited ones and ignore the ones coming from the source scene. This option
  150. is only present if materials are saved as files.
  151. Meshes
  152. ~~~~~~
  153. Compress
  154. ^^^^^^^^
  155. Makes meshes use less precise numbers for multiple aspects of the mesh in order
  156. to save space.
  157. These are:
  158. * Transform Matrix (Location, rotation, and scale) : 32-bit float to 16-bit signed integer.
  159. * Vertices : 32-bit float to 16-bit signed integer.
  160. * Normals : 32-bit float to 32-bit unsigned integer.
  161. * Tangents : 32-bit float to 32-bit unsigned integer.
  162. * Vertex Colors : 32-bit float to 32-bit unsigned integer.
  163. * UV : 32-bit float to 32-bit unsigned integer.
  164. * UV2 : 32-bit float to 32-bit unsigned integer.
  165. * Vertex weights : 32-bit float to 16-bit unsigned integer.
  166. * Armature bones : 32-bit float to 16-bit unsigned integer.
  167. * Array index : 32-bit or 16-bit unsigned integer based on how many elements there are.
  168. Additional info:
  169. * UV2 = The second UV channel for detail textures and baked lightmap textures.
  170. * Array index = An array of numbers that number each element of the arrays above; i.e. they number the vertices and normals.
  171. In some cases, this might lead to loss of precision, so disabling this option
  172. may be needed. For instance, if a mesh is very big or there are multiple meshes
  173. being imported that cover a large area, compressing the import of this mesh(es)
  174. may lead to gaps in geometry or vertices not being exactly where they should be.
  175. Ensure Tangents
  176. ^^^^^^^^^^^^^^^
  177. If textures with normal mapping are to be used, meshes need to have tangent arrays.
  178. This option ensures that these are generated if not present in the source scene.
  179. Godot uses Mikktspace for this, but it's always better to have them generated in
  180. the exporter.
  181. Storage
  182. ^^^^^^^
  183. Meshes can be stored in separate files (resources) instead of built-in. This does
  184. not have much practical use unless one wants to build objects with them directly.
  185. This option is provided to help those who prefer working directly with meshes
  186. instead of scenes.
  187. Light Baking
  188. ^^^^^^^^^^^^
  189. Whether or not the mesh is used in baked lightmaps.
  190. - **Disabled:** The mesh is not used in baked lightmaps.
  191. - **Enable:** The mesh is used in baked lightmaps.
  192. - **Gen Lightmaps:** The mesh is used in baked lightmaps, and unwraps a second UV layer for lightmaps.
  193. .. note:: For more information on light baking see :ref:`doc_baked_lightmaps`.
  194. External Files
  195. ~~~~~~~~~~~~~~
  196. Generated meshes and materials can be optionally stored in a subdirectory with the
  197. name of the scene.
  198. Animation options
  199. -----------------
  200. Godot provides many options regarding how animation data is dealt with. Some exporters
  201. (such as Blender) can generate many animations in a single file. Others, such as
  202. 3DS Max or Maya, need many animations put into the same timeline or, at worst, put
  203. each animation in a separate file.
  204. .. image:: img/scene_import3.png
  205. Import of animations is enabled by default.
  206. .. attention::
  207. To modify animations from an imported 3D scene, you need to change the animation
  208. storage option from **Built-In** to **Files** in the Import dock. Otherwise,
  209. changes made to animations from Godot will be lost when the project is run.
  210. FPS
  211. ~~~
  212. Most 3D export formats store animation timeline in seconds instead of frames. To ensure
  213. animations are imported as faithfully as possible, please specify the frames per second
  214. used to edit them. Failing to do this may result in shaky animations.
  215. Filter Script
  216. ~~~~~~~~~~~~~
  217. It is possible to specify a filter script in a special syntax to decide which tracks from which
  218. animations should be kept.
  219. The filter script is executed against each imported animation. The syntax consists of two types of
  220. statements, the first for choosing which animations to filter, and the second for filtering
  221. individual tracks within the matched animation. All name patterns are performed using a case
  222. insensitive expression match, using ``?`` and ``*`` wildcards (using ``String.matchn()`` under the
  223. hood).
  224. The script must start with an animation filter statement (as denoted by the line beginning with an
  225. ``@``). For example, if we would like to apply filters to all imported animations which have a name
  226. ending in ``"_Loop"``::
  227. @+*_Loop
  228. Similarly, additional patterns can be added to the same line, separated by commas. Here is a
  229. modified example to additionally *include* all animations with names that begin with ``"Arm_Left"``,
  230. but also *exclude* all animations which have names ending in ``"Attack"``::
  231. @+*_Loop, +Arm_Left*, -*Attack
  232. Following the animation selection filter statement, we add track filtering patterns to indicate
  233. which animation tracks should be kept or discarded. If no track filter patterns are specified, then
  234. all tracks within the matched animations will be discarded!
  235. It's important to note that track filter statements are applied in order for each track within the
  236. animation, this means that one line may include a track, a later rule can still discard it.
  237. Similarly, a track excluded by an early rule may then be re-included once again by a filter rule
  238. further down in the filter script.
  239. For example: include all tracks in animations with names ending in ``"_Loop"``, but discard any
  240. tracks affecting a ``"Skeleton"`` which end in ``"Control"``, unless they have ``"Arm"`` in their
  241. name::
  242. @+*_Loop
  243. +*
  244. -Skeleton:*Control
  245. +*Arm*
  246. In the above example, tracks like ``"Skeleton:Leg_Control"`` would be discarded, while tracks such
  247. as ``"Skeleton:Head"`` or ``"Skeleton:Arm_Left_Control"`` would be retained.
  248. Any track filter lines that do not begin with a ``+`` or ``-`` are ignored.
  249. Storage
  250. ~~~~~~~
  251. By default, animations are saved as built-in. It is possible to save them to a file instead. This
  252. allows adding custom tracks to the animations and keeping them after a reimport.
  253. Optimizer
  254. ~~~~~~~~~
  255. When animations are imported, an optimizer is run, which reduces the size of the animation considerably.
  256. In general, this should always be turned on unless you suspect that an animation might be broken due to it being enabled.
  257. Clips
  258. ~~~~~
  259. It is possible to specify multiple animations from a single timeline as clips. For this to work, the model
  260. must have only one animation that is named ``default``. To create clips, change the clip amount to something
  261. greater than zero. You can then name a clip, specify which frames it starts and stops on, and choose whether
  262. the animation loops or not.
  263. .. If this PR (https://github.com/godotengine/godot/pull/36709) is merged for Godot 4.0 this section must
  264. be updated to reflect that for the 4.0 documentation.
  265. Scene inheritance
  266. -----------------
  267. In many cases, it may be desired to make modifications to the imported scene. By default, this is not possible because
  268. if the source asset changes (source ``.dae``, ``.gltf``, ``.obj`` file re-exported from 3D modelling app), Godot will re-import the whole scene.
  269. It is possible, however, to make local modifications by using *Scene Inheritance*. Try to open the imported scene and the
  270. following dialog will appear:
  271. .. image:: img/scene_import4.png
  272. In inherited scenes, the only limitations for modifications are:
  273. * Nodes can't be removed (but can be added anywhere).
  274. * Sub-Resources can't be edited (save them externally as described above for this)
  275. Other than that, everything is allowed!
  276. Import hints
  277. ------------
  278. Many times, when editing a scene, there are common tasks that need to be done after exporting:
  279. - Adding collision detection to objects.
  280. - Setting objects as navigation meshes.
  281. - Deleting nodes that are not used in the game engine (like specific lights used for modelling).
  282. To simplify this workflow, Godot offers several suffixes that can be added to
  283. the names of the objects in your 3D modelling software. When imported, Godot
  284. will detect suffixes in object names and will perform actions automatically.
  285. .. note::
  286. All the suffixes described below are *case-sensitive*.
  287. Remove nodes (-noimp)
  288. ~~~~~~~~~~~~~~~~~~~~~
  289. Objects that have the ``-noimp`` suffix will be removed at import-time no matter
  290. what their type is. They will not appear in the imported scene.
  291. Create collisions (-col, -convcol, -colonly, -convcolonly)
  292. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  293. The option ``-col`` will work only for Mesh objects. If it is detected, a child
  294. static collision node will be added, using the same geometry as the mesh. This
  295. will create a triangle mesh collision shape, which is a slow, but accurate
  296. option for collision detection. This option is usually what you want for level
  297. geometry (but see also ``-colonly`` below).
  298. The option ``-convcol`` will create a :ref:`class_convexpolygonshape` instead of
  299. a :ref:`class_concavepolygonshape`. Unlike triangle meshes which can be concave,
  300. a convex shape can only accurately represent a shape that doesn't have any
  301. concave angles (a pyramid is convex, but a hollow box is concave). Due to this,
  302. convex collision shapes are generally not suited for level geometry. When
  303. representing simple enough meshes, convex collision shapes can result in better
  304. performance compared to a triangle collision shape. This option is ideal for
  305. simple or dynamic objects that require mostly-accurate collision detection.
  306. However, in both cases, the visual geometry may be too complex or not smooth
  307. enough for collisions. This can create physics glitches and slow down the engine
  308. unnecessarily.
  309. To solve this, the ``-colonly`` modifier exists. It will remove the mesh upon
  310. importing and will create a :ref:`class_staticbody` collision instead.
  311. This helps the visual mesh and actual collision to be separated.
  312. The option ``-convcolonly`` works in a similar way, but will create a :ref:`class_convexpolygonshape` instead.
  313. With Collada files the option ``-colonly`` can also be used with Blender's empty objects.
  314. On import, it will create a :ref:`class_staticbody` with
  315. a collision node as a child. The collision node will have one of a number of predefined shapes,
  316. depending on Blender's empty draw type:
  317. .. image:: img/3dimp_BlenderEmptyDrawTypes.png
  318. - Single arrow will create a :ref:`class_rayshape`.
  319. - Cube will create a :ref:`class_boxshape`.
  320. - Image will create a :ref:`class_worldmarginshape`.
  321. - Sphere (and the others not listed) will create a :ref:`class_sphereshape`.
  322. When possible, **try to use a few primitive collision shapes** instead of triangle
  323. mesh or convex shapes. Primitive shapes often have the best performance and
  324. reliability.
  325. .. note::
  326. For better visibility on Blender's editor, you can set the "X-Ray" option
  327. on collision empties and set some distinct color for them by changing
  328. **Edit > Preferences > Themes > 3D Viewport > Empty**.
  329. If using Blender 2.79 or older, follow these steps instead:
  330. **User Preferences > Themes > 3D View > Empty**.
  331. .. seealso::
  332. See :ref:`doc_collision_shapes_3d` for a comprehensive overview of collision
  333. shapes.
  334. Create navigation (-navmesh)
  335. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  336. A mesh node with the ``-navmesh`` suffix will be converted to a navigation mesh.
  337. The original Mesh object will be removed at import-time.
  338. Create a VehicleBody (-vehicle)
  339. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  340. A mesh node with the ``-vehicle`` suffix will be imported as a child to a
  341. :ref:`class_VehicleBody` node.
  342. Create a VehicleWheel (-wheel)
  343. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  344. A mesh node with the ``-wheel`` suffix will be imported as a child to a
  345. :ref:`class_VehicleWheel` node.
  346. Rigid Body (-rigid)
  347. ~~~~~~~~~~~~~~~~~~~
  348. A mesh node with the ``-rigid`` suffix will be imported as a :ref:`class_RigidBody`.
  349. Animation loop (-loop, -cycle)
  350. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  351. Animation clips in the COLLADA document that start or end with the token ``loop`` or ``cycle``
  352. will be imported as a Godot Animation with the loop flag set.
  353. **Unlike the other suffixes described above, this does not require a hyphen.**
  354. In Blender, this requires using the NLA Editor and naming the Action with the ``loop`` or
  355. ``cycle`` prefix or suffix.