diff --git a/docs/source/reference/modding/custom-models/index.rst b/docs/source/reference/modding/custom-models/index.rst index 8b6c5d87f7..b2d92032c5 100644 --- a/docs/source/reference/modding/custom-models/index.rst +++ b/docs/source/reference/modding/custom-models/index.rst @@ -18,7 +18,7 @@ Below is a quick overview of supported formats, followed by separate articles wi :caption: Table of Contents :maxdepth: 1 - pipeline-blender-collada pipeline-blender-collada-static-models + pipeline-blender-collada-animated-creature pipeline-blender-osgnative pipeline-blender-nif diff --git a/docs/source/reference/modding/custom-models/pipeline-blender-collada-animated-creature b/docs/source/reference/modding/custom-models/pipeline-blender-collada-animated-creature new file mode 100644 index 0000000000..b759bf9a02 --- /dev/null +++ b/docs/source/reference/modding/custom-models/pipeline-blender-collada-animated-creature @@ -0,0 +1,221 @@ +############################# +Animated Creature via COLLADA +############################# + +This tutorial shows how to get an animated creature from Blender to OpenMW using +the COLLADA format. It does not cover using Blender itself, as there are many +better resources for that. The focus is solely on the animation pipeline and its +specific requirements. Most of them are related to how the model, rig, and +animations are set up in Blender. + +.. note:: + This tutorial builds upon the :doc:`pipeline-blender-collada-static-models` tutorial. All fundamentals of exporting static objects apply to animated ones as well. + +Requirements +************ + +To use the Blender to OpenMW pipeline via COLLADA, you will need the following. + +* `OpenMW 0.48 `_ or later +* `Blender 2.83 `_ or later. Latest confirmed, working version is Blender 3.0 +* `OpenMW COLLADA Exporter `_ +* An animated model you would like to export. In our case the flamboyant Land Racer! + +The Land Racer +************** + +The creature, and its revelant files, are available from the `Example Suite repository `_. +This should be useful for further study of how to set things up in case this +tutorial is not clear on any particular thing. + +* ``data/meshes/land_racer.dae`` – exported model +* ``data/meshes/land_racer.txt`` – animation textkeys +* ``data/textures/land_racer.dds`` – diffuse texture +* ``data/textures/land_racer_n.dds`` - normal map +* ``source_assets/land_racer.blend`` – source file configured as this tutorial specifies + +Model +***** + +The model needs to be a child of the rig and have an Armature modifier asigned. +Bone weights are limited to a maximum of 4 bones per vertex. The model needs to +have default location, rotation, and scale. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-in-blender.jpg + :align: center + + +Collision Shape +*************** + +Collision is set up with an empty named ``Collision`` or ``collision`` with a +single child mesh. OpenMW will use the bounding box of this mesh for physics +collision shape so a simple, cuboid mesh is enough. If no collision shape is +defined, the bounding box of the animated model will be used instead. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-collision-shape.jpg + :align: center + + +Armature / Rig +************** + +.. note:: + Only a single rig object should be included in the exported file. Exporting multiple rigs is not reliably supported and can lead to errors. + +Root +---- + +The rig needs to be structured in a specific way. There should be a single top +bone in the rig’s hierarchy, the root bone named ``Bip01``. The name is +required so OpenMW recognizes and uses it for root movement. For this same +reason, the bone should be by default aligned with the world. The root bone +needs to have its ``Deform`` flag **enabled**. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-root-bone.jpg + :align: center + + +Deform Bones +------------ + +Below the root bone, the bones are divided into two branches. One branch +contains the deform bones which get included in the final exported file. These +are otherwise not animated directly but inherit motion from other bones via +constraints. They have their ``Deform`` flag **enabled**. For creatures, the +deform bones can be named as you desire and don’t need to follow the naming +convention used for NPC and player models. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-rig-hierarchy.jpg + :align: center + +Control Bones +------------- + +The other branch holds control and helper bones that enable comfortable +animation in Blender, but are neither required nor included in the exported +file. They have their ``Deform`` flag **disabled**. How these bones are +structured is a big separate topic on its own that this tutorial does not cover, +but you can study the provided source file. + + +Animations +********** + +A creature in OpenMW is expected to have a set of animations to display its +various actions. These animations are recognized and used by their name. + +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * - Animation name + - Possible variations + - Purpose + * - attack1 + - attack2, attack3 + - The creature performs an attack + * - death1 + - death2 - death5 + - The creature dies while upright + * - hit1 + - hit2 - hit5 + - The creature is hit in combat + * - idle + - idle2 - idle9 + - Flavour animations when the creature does nothing in particular + * - knockout + - / + - When creature's fatigue goes below 0 and it staggers to the ground + * - deathknockout + - / + - The creature dies while knocked out + * - knockdown + - / + - When the creatures receives a heavy hit in combat or lands from a considerable height + * - deathknockdown + - / + - The creature dies while knocked down + * - runforward + - / + - Moving forward fast + * - walkforward + - / + - Moving forward at regular speed + +Animating in Blender is done at 30 fps. Specific to how OpenMW works, each +exported animation needs to take a unique range on the timeline. To achieve +this, actions are placed as strips in the NLA editor with an obligatory one +frame gap between them. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-nla-strips.jpg + :align: center + +NLA strips affect the exported result based on their scale, name, frame range, +repetition, or any other factor affecting the end animation result. It's +*What you see is what you get* principle. + +Root movement is required for animations such as ``walkforward`` and +``runforward`` and is likely to work for other animations if needed. +Root movement works only when the root bone is named ``Bip01``. + +Textkeys +******** + +The exported COLLADA file requires a corresponding textkeys file for OpenMW to +properly read the animations. Textkeys is a ``.txt`` file containing animation +definitions and events. At a minimum it needs to include at least animation +``start`` and ``stop`` values in a format as shown in this example. + +.. code:: + + idle: start 0.033333 + idle: stop 2.033333 + walkforward: start 2.066667 + walkforward: stop 3.666667 + runforward: start 3.7 + runforward: stop 4.433333 + attack1: start 4.466667 + attack1: stop 5.433333 + ... + +The textkeys file is placed in the same folder as the model and matches the model's name. + +* ``meshes/land_racer.dae`` +* ``meshes/land_racer.txt`` + +While it's possible to write it by hand, OpenMW's Collada Exporter offers a +convenient option to export a textkeys file based on Blender's timeline markers +(not to be confused with pose markers which are contained per action). What you +need to do is create properly named timeline markers for each animation and +enable the ``Export Textkeys`` option in the exporter. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-textkey-markers.jpg + :align: center + +In the example of ``walkforward`` the timeline markers should be named +``walkforward: start`` and ``walkforward: stop``. + + +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. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-exporter-settings.jpg + :align: center + + +Getting the Model In-game +************************* + +Once the Land Racer is exported, both of its ``.dae`` and ``.txt`` files need to +be placed in the correct folder where OpenMW will read it. Afterwards in +OpenMW-CS, it should be visible in the Assets->Meshes table and can be assigned +to the ``Model/Animation`` field of a creature. + +.. image:: https://gitlab.com/OpenMW/openmw-docs/-/raw/master/docs/source/reference/modding/custom-models/_static/landracer-in-openmwcs.jpg + :align: center +