From ee2bcff6942ed64649ca7377b2713a1079d6cb19 Mon Sep 17 00:00:00 2001 From: Lamoot Date: Sun, 18 Apr 2021 15:52:11 +0200 Subject: [PATCH 1/3] Various improvements to the COLLADA format asset pipeline page. Added images. Added more information on how to define textkeys. Always use all capitals for the COLLADA format name. Barebones subsections for materials and collisions. --- .../pipeline-blender-collada.rst | 95 +++++++++++++------ 1 file changed, 68 insertions(+), 27 deletions(-) diff --git a/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst b/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst index 48a19cb7c..ac60febae 100644 --- a/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst +++ b/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst @@ -1,79 +1,120 @@ ############################## -Blender to OpenMW with Collada +Blender to OpenMW with COLLADA ############################## -First, let's take a look at the pipeline requirements and how the fundamental properties of a scene translate from Blender to OpenMW. - Requirements ------------- +************ +To use the Blender to OpenMW pipeline via COLLADA, you will need the following. + * `OpenMW 0.47 `_ or later * `Blender 2.81 `_ or later. Latest confirmed, working version is Blender 2.91 * `Better COLLADA Exporter `_ tuned for OpenMW * A model you would like to export -In addition, OpenMW needs to be configured to read COLLADA (dae) files instead of the default format (nif). In settings.cfg under [Models] section... TODO + +Static Models +************* +Static models are those that don't have any animations included in the exported file. First, let's take a look at how the fundamental properties of a scene in Blender translate to a COLLADA model suitable for use in OpenMW. These apply the same to static and animated models. Location --------- +======== Objects keep their visual location and origin they had in the original scene. - Rotation --------- +======== * Blender’s +Z axis is up axis in OpenMW * Blender’s +Y axis is front axis in OpenMW * Blender’s X axis is left-right axis in OpenMW - Scale ------ +===== + +Scale ratio between Blender and OpenMW is 70 to 1. This means 70 units in Blender translate to 1 m in OpenMW. + +However, a scale factor like this is impractical to work with. A better approach is to work with a scale of 1 Blender unit = 1 m and apply the 70 scale factor at export. The exporter will automatically scale all object, mesh, armature and animation data. + +Materials +========= + +In Blender, use the Principled BSDF node with textures plugged into the correct sockets. TODO... -Scale ratio between Blender and OpenMW is 70 to 1. This means 70 blender units translate to 1 m in OpenMW. +Collision Shapes +================ -However, a scale factor like this is impractical to work with. A better approach is to work with a scale of 1 Blender unit = 1m and apply the 70 scale factor in the Better COLLADA Exporter. The exporter will automatically scale all object, mesh, armature and animation data. +In Blender, have an empty object named ``Collision`` with child meshes. These meshes are regarded as collision shapes. TODO... +Exporter Settings +================= + +For static models, use the following exporter settings. Before export, select all objects you wish to include in the exported file and have the "Selected Objects" option enabled. Without this, the exporter could fail. -Exporter settings - static models ---------------------------------- -Better COLLADA Exporter offers various options which are rather straightforward for static models. The important one is last in the list, to apply a scaling factor of 70 to the whole scene, so 1 blender unit equals 1 m in OpenMW. The following settings should be good for general use. -It's also very important to have "export selected" box checked, as otherwise the exporter may just fail with an error message. It's also important to have the correct window open, and the models selected before exporting. +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/dae_exporter_static.jpg + :align: center -Animated models to OpenMW -------------------------- +Animated Models +*************** Animated models are those where a hierarchy of bones, known as armature, deforms the mesh and makes things move. Besides the topics covered above, the following requirements apply. Armature --------- +======== -* For animated models, a single armature per COLLADA file is advised to avoid any potential problems. +* A single armature per COLLADA file is advised to avoid any potential problems. * There needs to be a single top-most bone in the armature’s hierarchy, where both the deformation and control bones fall under it. * Not all bones need to be exported. By disabing the bone’s “Deform” property and using the corresponding option in the exporter, it is possible to export only the bones needed for animation. Animations ----------- +========== Every action in Blender is exported as its own animation clip in COLLADA. Actions you don't wish to export need to have "-noexp" added to their name, with the corresponding option enabled in the exporter. -Due to current limitations of the format / exporter, the keyframes of any action must not overlap the keyframes of any other action. Thus in practice, the keyframes for each action need to be manually offset to their unique range on the timeline. +Due to current limitations of the format and exporter, the keyframes of individual actions must not overlap with other actions. The keyframes need to be manually offset to a unique range on the timeline as shown in this example. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/dae_animations_on_timeline.jpg + :align: center + +Textkeys +-------- -An animated .dae file needs a corresponding animation definition file, or textkeys, for OpenMW to understand. Textkeys are set in .txt file with the same name as the model. E.g. OpenMWDude.dae -> OpenMWDude.txt , each line having a textkey and a double number for timesignature. E.g. idle: start 0.03333333333333333. +The exported COLLADA file requires a corresponding textkeys file for OpenMW to properly read the animations. Textkeys is a .txt file containing animation definitions. Textkeys file is placed in the same folder as the model and uses a name matching the model. + + - ``OpenMWDude.dae`` + - ``OpenMWDude.txt`` + +Textkeys use a simple format as shown in the example. Name, start and stop values can be taken from the corresponding COLLADA file for each ````. + +.. code:: + + idle: start 0.03333333333333333 + idle: stop 2.033333333333333 + runforward: start 2.0666666666666664 + runforward: stop 3.0666666666666664 + runback: start 3.1 + runback: stop 4.1 + ... + Root Motion ------------ +=========== -OpenMW can read the movement of the root (top-most) bone and use it to move objects in the game world. For this to work, the root bone must be animated to move through space. The root bone must, in its default pose, be alligned with the world. +OpenMW can read the movement of the root (top-most in hierarchy) bone and use it to move objects in the game world. For this to work, the root bone must be animated to move through space. The root bone must, in its default pose, be alligned with the world. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/dae_rig_root.jpg + :align: center Exporter Settings ------------------ +================= + +For animated models, use the following exporter settings. Before export, select all objects you wish to include in the exported file and have the "Selected Objects" option enabled. Without this, the exporter could fail. -For animated models, use the following exporter settings. Before export, select all objects you wish to include in the exported file. TODO +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/dae_exporter_animated.jpg + :align: center From 8b40128559d1820bc053562bcb8108a30a9c3f3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matja=C5=BE=20Lamut?= Date: Sun, 18 Apr 2021 15:14:36 +0000 Subject: [PATCH 2/3] Finish the section on how to set up collision shapes in Blender. --- .../modding/custom-models/pipeline-blender-collada.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst b/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst index ac60febae..5af136f74 100644 --- a/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst +++ b/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst @@ -43,7 +43,7 @@ In Blender, use the Principled BSDF node with textures plugged into the correct Collision Shapes ================ -In Blender, have an empty object named ``Collision`` with child meshes. These meshes are regarded as collision shapes. TODO... +In Blender, create an empty and name it ``collision``. Any mesh that is a child of this empty will be used for physics collision and will not be visible. There can be multiple child meshes under ``collision`` and they will all contribute to the collision shapes. The meshes themselves can have an arbitrary name, it's only the name of the empty that is important. The ``tcb`` command in OpenMW's in-game console will make the collision shapes visible and you will be able to inspect them. Exporter Settings ================= From 4d4fc5ed0be709eb506f893435005dd78084d341 Mon Sep 17 00:00:00 2001 From: Lamoot Date: Sun, 18 Apr 2021 21:28:20 +0200 Subject: [PATCH 3/3] Finish the section on materials setup. --- .../modding/custom-models/pipeline-blender-collada.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst b/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst index 5af136f74..47096a83e 100644 --- a/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst +++ b/docs/source/reference/modding/custom-models/pipeline-blender-collada.rst @@ -38,7 +38,9 @@ However, a scale factor like this is impractical to work with. A better approach Materials ========= -In Blender, use the Principled BSDF node with textures plugged into the correct sockets. TODO... +OpenMW uses the classic, specular material setup and currently doesn't use the more mainstream `PBR `_ way. In Blender, the mesh needs a default material with a diffuse texture connected to the ``Base Color`` socket. This is enough for the material to be included in the exported COLLADA file. + +Additional texture types, such as specular or normal maps, will be automatically recognized and used by OpenMW. They need an identical base name as the diffuse texture, a suffix, and be in the same folder. How to enable this and what suffix is used for what texture type is covered in more detail in :doc:`../../modding/texture-modding/texture-basics`. Collision Shapes ================