diff --git a/img/scene_import1.png b/img/scene_import1.png new file mode 100644 index 000000000..df303fc18 Binary files /dev/null and b/img/scene_import1.png differ diff --git a/img/scene_import2.png b/img/scene_import2.png new file mode 100644 index 000000000..78cc07b4d Binary files /dev/null and b/img/scene_import2.png differ diff --git a/img/scene_import3.png b/img/scene_import3.png new file mode 100644 index 000000000..8cd9c5384 Binary files /dev/null and b/img/scene_import3.png differ diff --git a/img/scene_import4.png b/img/scene_import4.png new file mode 100644 index 000000000..b5afa5a95 Binary files /dev/null and b/img/scene_import4.png differ diff --git a/learning/workflow/assets/importing_scenes.rst b/learning/workflow/assets/importing_scenes.rst new file mode 100644 index 000000000..3df876220 --- /dev/null +++ b/learning/workflow/assets/importing_scenes.rst @@ -0,0 +1,281 @@ +.. _doc_importing_3d_scenes: + +Importing 3D Scenes +================== + +Godot Scene Importer +-------------------- + +When dealing with 3D assets, Godot has a very flexible and configurable asset pipeline. While the defaults may be +enough for most users. + +Godot mainly works with *scenes*. By default, it can import *scene files* in GLTF2.0, DAE (Collada), and OBJ (Wavefront) formats. +Just copy the scene file together with the texture to the project repository, and Godot will do a full import. + +Why not FBX? +~~~~~~~~~~~~ + +Most game engines use the FBX format for importing 3D scenes, which is +definitely one of the most standardized in the industry. However, this +format requires the use of a closed library from Autodesk which is +distributed with a more restrictive licensing terms than Godot. The plan +is, sometime in the future, to implement an external conversion binary, +but meanwhile FBX is not supported. + +Exporting DAE files from Maya and 3DS Max +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Autodesk added built-in collada support to Maya and 3DS Max, but it's +really broken and should not be used. The best way to export this format +is by using the +`OpenCollada `__ +plugins. They work really well, although they are not always up-to date +with the latest version of the software. + +Exporting DAE files from Blender +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Blender also has built-in collada support, but it's really broken and +should not be used either. + +Godot provides a `Python +Plugin `__ +that will do a much better job at exporting the scenes. + +Import workflows +---------------- + +Godot scene importer allows different workflows regarding how data is imported. Depending on many options, it is possible to +import a scene with: + +* Extenal materials (default): Where each material is saved to a file resource. Modifications to them are kept. +* External meshes: Where each mesh is saved to a different file. Many users prefer to deal with meshes directly. +* External animations: Allowing animations saved to be modified and merged when sources change. +* External scenes: Save the root nodes of the imported scenes each as a separate scene. +* Single Scene: A single scene file with everything built in. + +.. image:: /img/scene_import1.png + +As different developers have different needs, this import process is highly customizable. + +Import Options +--------------- + +The importer has several options, which will be discussed below: + +.. image:: /img/scene_import2.png + +Nodes : Root Type +^^^^^^^^^^^^^^^^^ + +By default the type of the root node in imported scenes is "Spatial", but this can be modified. + +Nodes : Root Name +^^^^^^^^^^^^^^^^^ + +Allows setting a specific name to the generated root node. + +Nodes : Custom Script +^^^^^^^^^^^^^^^^^^^^^ + +A special script to process the whole scene after imported can be provided. +This is great for post processing, changing materials, doing funny stuff +with the geometry, etc. + +Create a script that basically looks like this: + +:: + + tool # needed so it runs in editor + extends EditorScenePostImport + + func post_import(scene): + # do your stuff here + return scene # remember to return the imported scene + +The post-import function takes the imported scene as argument (the +parameter is actually the root node of the scene). The scene that +will finally be used must be returned. It can be a different one. + +Nodes : Storage +^^^^^^^^^^^^^^^ + +By default Godot imports a single scene. This option allows specifying +that nodes below the root will each be a separate scene and instanced +into the imported one. + +Of course, instancing such imported scenes in other places manually works too. + + +Materials : Location +^^^^^^^^^^^^^^^^^^^^ + +Godot supports materials in meshes or nodes. By default, materials will be put +on each node. + +Materials : Storage +^^^^^^^^^^^^^^^^^^^ + +Materials can be stored within the scene or in external files. By default +they are stored in external files so editing them is possible. This is because +most 3D DCCs don't have the same material options that are present in Godot. + +When materials are built-in, they will be lost each time the source scene +is modified and re-imported. + +Materials : Keep on Reimport +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once materials are edited to use Godot features, the importer will keep the +edited ones and ignore the ones coming from the source scene. This option +is only present if materials are saved as files. + +Meshes : Compress +^^^^^^^^^^^^^^^^^ + +Makes meshes compact 3D vertices to more efficient data types for rendering. +In few cases, this might lead to precision loss so disabling this option +is allowed. + +Meshes : Ensure Tangents +^^^^^^^^^^^^^^^^^^^^^^^^ + +If textures with normalmapping are to be used, meshes need to have tangent arrays. +This option ensures that these are generated if not present in the source scene. +Godot uses Mikktspace for this, but it's always better to have them generated in +the exporter. + +Meshes : Storage +^^^^^^^^^^^^^^^^ + +Meshes can be stored in separate files (resources) instead of built in. This does +not have much practical use unless wanting to build objects with them directly. + +This option is provided to help those who prefer working directly with meshes +instead of scenes. + +External Files : Store in Subdir +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Generated meshes and materials can be optionally, stored in a subdirectory with the +name of the scene. + +Animation Options +----------------- + +Godot provides many options regarding how animation data is deal with. Some exporters +(such as Blender), can generate many animations in a single file. Others, such as +3DS Max or Maya, need many animatiosn put into the same timeline or, at worse, put +each animation in a separate file. + +.. image:: /img/scene_import3.png + +Import of animations is enabled by default. + +Animation : FPS +~~~~~~~~~~~~~~~ + +Most 3D export formats store animation timeline in seconds instead of frames. To ensure +animations are imported as faithfully as possible, please specify the frames per second +used to edit them. Failing to do this may result in minimal jitter. + +Animation : Filter Script +~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to specify a filter script in a special syntax to decide which tracks from which +animations should be kept. (@TODO this needs documentation) + +Animation : Storage +~~~~~~~~~~~~~~~~~~~ + +By default, animations are saved as built-in. It is possible to save them to a file instead. This +allows adding custom tracks to the animations and keeping them after a reimport. + + +Animation : Optimizer +~~~~~~~~~~~~~~~~~~~~~ + +When animations are imported, an optimizer is run which reduces considerable the size of the animation. +In general this should always be turned on unless you suspect that an animation might be broken due to it being enabled. + +Animation : Clips +~~~~~~~~~~~~~~~~~~~~~ + +It is possible to specify multiple animations from a single timeline as clips. Just specify from which frame to which frame each +clip must be taken from (and, of course, don't forget to specify the FPS option above) + +Scene Inheritance +----------------- + +In many cases, it may be desired to do modifications to the imported scene. By default, this is not really possible because +if the source asset changes (source .dae,.gltf,.obj file re-exported from 3D modelling app) Godot will re-import the whole scene. + +It is possible, however, to do local modifications by using *Scene Inheritance*. Just try to open the imported scene and the +following dialog will appear: + +.. image:: /img/scene_import4.png + +In inherited scenes, the only limitations for modifications are: +* Nodes can't be removed (but can be added anywhere). +* Sub-Resources can't be edited (save them externally as described above for this) + +Other than that, everything is allowed! + +Import Hints +------------ + +Many times, when editing a scene, there are common tasks that need to be done after exporting: +* Adding collision detection to objects: +* Setting objects as navigation meshes +* Deleting nodes that are not used in the game engine (like specific lights used for modelling) + +To simplify this workflow, Godot offers a few suffixes that can be added to the names of the +objects in your 3D modelling software. When imported, Godot will detect them and perform +actions automatically: + +Remove nodes (-noimp) +^^^^^^^^^^^^^^^^^^^^^ + +Node names that have this suffix will be removed at import time, mo +matter what their type is. They will not appear in the imported scene. + +Create collisions (-col, -colonly) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Option "-col" will work only for Mesh nodes. If it is detected, a child +static collision node will be added, using the same geometry as the mesh. + +However, it is often the case that the visual geometry is too complex or +too un-smooth for collisions, which ends up not working well. + +To solve this, the "-colonly" modifier exists, which will remove the mesh upon +import and create a :ref:`class_staticbody` collision instead. +This helps the visual mesh and actual collision to be separated. + +Option "-colonly" can be also used with Blender's empty objects. +On import it will create a :ref:`class_staticbody` with +collision node as a child. Collision node will have one of predefined shapes, +depending on the Blender's empty draw type: + +.. image:: /img/3dimp_BlenderEmptyDrawTypes.png + +- Single arrow will create :ref:`class_rayshape` +- Cube will create :ref:`class_boxshape` +- Image will create :ref:`class_planeshape` +- Sphere (and other non-listed) will create :ref:`class_sphereshape` + +For better visibility in Blender's editor user can set "X-Ray" option on collision +empties and set some distinct color for them in User Preferences / Themes / 3D View / Empty. + +Create navigatopm (-navmesh) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A mesh node with this suffix will be converted to a navigation mesh. Original Mesh node will be +removed. + +Create navigatopm (-rigid) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a rigid body from this mesh + + diff --git a/learning/workflow/assets/index.rst b/learning/workflow/assets/index.rst index 07ee700a3..dc783634d 100644 --- a/learning/workflow/assets/index.rst +++ b/learning/workflow/assets/index.rst @@ -9,4 +9,5 @@ Assets workflow importing_images importing_audio_samples importing_translations + importing_scenes