Add godot-blender-export doc (#1501)

* add a directory to place godot-blender-exporter doc

* Added documentation for physics, lights and materials export

getting_started/workflow/assets/escn_exporter/index.rst

@@ -0,0 +1,36 @@
+Godot-Blender-Exporter
+======================
+
+Details on exporting
+--------------------
+.. toctree::
+   :maxdepth: 1
+   :name: toc-learn-workflow-assets-escn_exporter
+
+   material
+   physics
+   lights
+
+
+Disabling specific objects
+--------------------------
+Sometimes you don't want some objects exported (eg high-res models used for
+baking). An object will not be exported if it is not rendered in the scene.
+This can be set in the outliner:
+
+.. image:: img/hide.jpg
+
+Objects hidden in the viewport will be exported, but will be hidden in the
+Godot scene.
+
+
+Build Pipeline Integration
+--------------------------
+If you have hundreds of model files, you don't want your artists to waste time
+manually exporting their blend files. To combat this, the exporter provides a
+python function ``io_scene_godot.export(out_file_path)`` that can be called to
+export a file. This allows easy integration with other build systems. An
+example Makefile and python script that exports all the blends in a directory
+is present in the Godot-Blender-exporter repository.
+
+

getting_started/workflow/assets/escn_exporter/lights.rst

@@ -0,0 +1,27 @@
+Lights
+======
+.. warning::
+    By default, lamps in Blender have shadows enabled. This can cause
+    performance issues in Godot.
+
+.. warning::
+    Lamps are exported using their "Blender Render" settings. When Blender 2.8
+    is released, this will be removed and this part of the exporter will change.
+
+Sun, point and spot lamps are all exported from Blender along with many of their
+properties:
+
+.. image:: img/light_properties.jpg
+
+There are some things to note:
+
+ - In Blender, a light casts light all the way to infinity. In Godot, it is
+   clamped by the attenuation distance. To most closely match between the
+   viewport and Godot, enable the "Sphere" checkbox. (Highlighted green)
+ - Light attenuation models differ between Godot and Blender. The exporter
+   attempts to make them match, but it isn't always very good.
+ - Spotlight angular attenuation models also differ between Godot and Blender.
+   The exporter attempts to make them similar, but it doesn't always look the
+   same.
+ - There is no difference between buffer shadow and ray shadow in the export.
+

getting_started/workflow/assets/escn_exporter/material.rst

@@ -0,0 +1,49 @@
+Materials
+=========
+
+Using existing Godot materials
+--------------------------------
+One way in which the exporter can handle materials is to attempt to match
+the Blender material with an existing Godot material. This has the advantage of
+being able to use all of the features of Godot's material system, but it means
+that you cannot see your model with the material applied inside Blender.
+
+To do this, the exporter attempts to find Godot materials with names that match
+those of the material name in Blender. So if you export an object in Blender
+with the material name ``PurpleDots`` then the exporter will search for the
+file ``PurpleDots.tres`` and assign it to the object. If this file is not a
+``SpatialMaterial`` or ``ShaderMaterial`` or if it cannot be found, then the
+exporter will fall back to exporting the material from Blender.
+
+
+Where the exporter searches for the ``.tres`` file is determined by the "Material
+Search Paths" option:
+
+.. image:: img/material_search.jpg
+
+This can take the value of:
+ - Project Directory - Attempts to find the ``project.Godot`` and recursively
+   searches through subdirectories. If ``project.Godot`` cannot be found it
+   will throw an error. This is useful for most projects where naming conflicts
+   are unlikely.
+ - Export Directory - Look for materials in subdirectories of the export
+   location. This is useful for projects where you may have duplicate
+   material names and need more control over what material gets assigned.
+ - None - Do not search for materials. Export them from the Blender file.
+
+
+Export of Blender materials
+---------------------------
+
+The other way materials are handled is for the exporter to export them from
+Blender. Currently only the diffuse color and a few flags (eg unshaded) are
+exported.
+
+.. warning::
+	Export of Blender materials is currently very primitive. However, it is the
+	focus of a current GSOC project
+
+.. warning::
+	Materials are currently exported using their "Blender Render" settings.
+	When Blender 2.8 is released, this will be removed and this part of the
+	exporter will change.

getting_started/workflow/assets/escn_exporter/physics.rst

@@ -0,0 +1,57 @@
+Physics Properties
+==================
+Exporting physics properties is done by enabling "Rigid Body" in Blenders
+physics tab:
+
+.. image:: img/enable_physics.png
+
+.. important::
+    By default, a single Blender object with rigid body enabled will export as
+    three nodes: a PhysicsBody, a CollisionShape, and a MeshInstance.
+
+
+Body Type
+---------
+Blender only has the concept of "Active" and "Passive" rigid bodies. These
+turn into Static and RigidBody nodes. To create a kinematic body, enable the
+"animated" checkbox on an "Active" body:
+
+.. image:: img/body_type.jpg
+
+
+Collision Shapes
+----------------
+Many of the parameters for collision shapes are missing from Blender, and many
+of the collision shapes are also not present. However, almost all of the
+options in Blender's rigid body collision and rigid body dynamics interfaces
+are supported:
+
+.. image:: img/collision_shapes.jpg
+
+There are the following caveats:
+ - Not all of the collision shapes are supported. Only ``Mesh``, ``Convex
+   Hull``, ``Capsule``, ``Sphere`` and ``Box`` are supported in both Blender and
+   Godot
+ - In Godot, you can have different collision groups and collision masks. In
+   Blender you only have collision groups. As a result, the exported object's
+   collision mask is equal to it's collision group. Most of the time, this is
+   what you want.
+
+.. important
+	To build compound physics shapes, parent together multiple objects with
+	rigid body enabled. The physics properties are taken from the parent-most
+	rigid body, and the rest are used as collision shapes.
+
+
+Collision Geometry Only
+-----------------------
+Frequently you want different geometry for your collision meshes and your
+graphical meshes, but by default the exporter will export a mesh along with the
+collision shape. To only export the collision shape, set the objects maximum
+draw type to Wire:
+
+.. image:: img/col_only.png
+
+This will also influence how the object is shown in Blender's viewport.
+Most of the time, you want your collision geometry to be shown see-through when
+working on the models, so this works out fairly nicely.

getting_started/workflow/assets/importing_scenes.rst

@@ -49,6 +49,17 @@ Godot provides a `Python
 Plugin <https://github.com/godotengine/collada-exporter>`__
 that will do a much better job of exporting the scenes.
 
+Exporting ESCN files from Blender
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The most powerful one, called `godot-blender-exporter
+<https://github.com/godotengine/godot-blender-exporter>`__. 
+It uses .escn files which is kind of another name of .tscn file(Godot scene file),
+it keeps as much information as possible from a Blender scene.
+
+ESCN exporter has a detailed `document <escn_exporter/index.html>`__ describing
+its functionality and usage.
+
 Import workflows
 ----------------
 

getting_started/workflow/assets/index.rst

@@ -10,4 +10,4 @@ Assets workflow
    importing_audio_samples
    importing_translations
    importing_scenes
-
+   escn_exporter/index