Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/antoniond/dsma-library

DS Model Animation Library
https://github.com/antoniond/dsma-library

3d-models demoscene homebrew md5-models nintendo-ds

Last synced: 4 days ago
JSON representation

DS Model Animation Library

Awesome Lists containing this project

README 

        
DSMA Library

============



Introduction

------------



**DSMA** (DS Model Animation) is a library that allows you to convert animated

models saved in MD5 format into a format that can be displayed in the Nintendo DS

in a very efficient way. This library depends on **libnds**. You can use the

library with `BlocksDS `_ or `devkitPro

`_. The examples in this repository use BlocksDS.



MD5 supports skeletal animation, which lets you reuse the same model with

multiple animations (a **md5mesh** file can be used with multiple **md5anim**

files). This library works in a similar way.



The converter used for this library is called **md5_to_dsma**, and it generates

the following files:



- **DSM** (DS Model): It contains a display list with the geometry of the model.

- **DSA** (DS Animation): It contains the position and orientation of all bones

  in a specific animation sequence. You can have multiple DSA files for a single

  DSM model if you have multiple animations for it.



The library supports interpolation between frames so that DSA files can have a

smaller size by reducing the number of stored frames in it. It also supports

blending two animations to make seamless transitions between them.



You are expected to load the files in some way (either including them as binary

data in your game, or loading them from the filesystem) and pass them to the

functions exposed by the library header.



There are multiple examples of how to use the library in this repository. They

all use libnds, and most of the 3D setup code is generic libnds 3D setup code.

You can build them with `BlocksDS `_ and you

can test them with an emulator such as **DeSmuME** or **melonDS** or in real

hardware with a flashcard.



- **basic_model**: Simply load an animated model embedded in the binary.

- **blended_animations**: Blend two animations in the same model.

- **filesystem_loading**: Load models from the filesystem (with **nitroFS**).

  Note that this example won't work in **melonDS** if it's built with devkitPro

  due to a bug in their implementation of NitroFS.

- **multiple_animations**: Display one model with multiple animations.

- **performance**: Show how much CPU time it takes to draw an animated model.

- **stress_test**: Show multiple animated models with different animations.



You can download them pre-compiled from the **Releases** page on GitHub:



https://github.com/AntonioND/dsma-library/releases



This is an example of multiple models being displayed on the screen:



.. image:: examples/stress_test/screenshot.png



The library is under the MIT license, and the examples are licensed under the

CC0 license.



To get the latest version of this library, go to the repository:

https://github.com/AntonioND/dsma-library



Generating and converting MD5 models

------------------------------------



You can't use any MD5 model with this library. There is a limit in the number of

bones in the skeleton used in your model. Each bone transformation is stored as

one matrix in the DS matrix stack, which means that you have, at best, space for

29 bones. However, in most cases, the actual space will be smaller (because the

program also uses that space).



Also, it isn't possible to have multiple weights for the same vertex. The MD5

format mandates that all vertices are assigned at least one weight, but

``md5_to_dsma`` will make sure that all vertices have assigned exactly one weight

with a value of 1.0.



You can use any 3D design tool to create your models, as long as you can export

them as MD5 later. Personally, I use blender to generate my models, and I use

this addon https://github.com/KozGit/Blender-2.8-MD5-import-export-addon to

export them as MD5 files. In short: Design your model as usual, making sure that

all your weights are 1.0. Then, clean up the weights of the model (to remove any

weight of 0.0, the exporter will fail if they aren't removed). Make sure that

all the bones have been moved to layer 5 (so that the exporter finds them) and

export the model and animations.



``md5_to_dsma`` can be used to convert a ``md5mesh`` file, a list of ``md5anim``

files, or both at the same time.



Convert all files in one run:



.. code::



    md5_to_dsma.py --model Robot.md5mesh \

                   --name robot \

                   --output out_folder \

                   --texture 128 128 \

                   --anim Wave.md5anim Walk.md5anim Bow.md5anim



Convert the mesh only:



.. code::



    md5_to_dsma.py --model Robot.md5mesh \

                   --name robot \

                   --output out_folder \

                   --texture 128 128



Convert the animations only:



.. code::



    md5_to_dsma.py --anim Wave.md5anim Walk.md5anim Bow.md5anim \

                   --name robot \

                   --output out_folder



Converting textures

-------------------



In order to convert textures you can use:



- **grit**: Distributed by BlocksDS and devkitPro. It supports all texture

  formats except for Tex4x4.

- `ptexconv `_: It supports all texture

  formats, even Tex4x4.



``md5_to_dsma``

---------------



The options supported are:



- ``--output``: Output folder. It will be created if it doesn't exist.



- ``--model``: ``md5mesh`` file to convert. All MD5 models come with a base

  pose, which is exported as a DSA file. The model itself is saved as a DSM

  file.



- ``--texture``: Texture size of the model. This is required. The DS doesn't

  use floating point values for texture coordinates, so you can only use

  textures of the size specified when converting the model. For example, a 32x64

  texture, do ``--texture 32 64``.



- ``--anims``: List of ``md5anim`` files to convert. Each animation is saved as

  a DSA file.



- ``--name``: Base name used for the output files.



- ``--blender-fix``: Blender uses Z as "up" axis, but the DS uses Y as "up".

  This makes it very awkward to export models from Blender to DS. This option

  rotates them by -90 degrees on the X axis so that they use the natural system

  of coordinates of the DS instead of the one of Blender.



- ``--bin``: When this is used, ``.bin`` is added to the end of all the names of

  the files generated by the tool. This is useful if you want to copy the files

  to a ``data`` folder of a libnds template and you don't want to modify the

  ``Makefile`` to accept new file extensions. This option isn't required if you

  are using **libfilesystem**, **libfat** or similar and you're loading files

  from a filesystem.



- ``--export-base-pose``: ``md5mesh`` files contain a base pose. This option

  will export this base pose as a DSA file with one frame.



- ``--skip-frames``: Number of animation frames to skip after exporting each

  frame. For example, to skip half of the frames, do ``--skip-frames 1``, and to

  only export 25% of the frames, do ``--skip-frames 3``.



- ``--draw-normal-polygons``: This is only useful for debugging. It will export

  additional polygons that represent the normals of the model in its base pose

  (they won't move when you animate the model).



Displaying models on the NDS

----------------------------



The library only has three functions:



- ``DSMA_GetNumFrames()``



  Returns the number of frames of the animation in a DSA file.



- ``DSMA_DrawModel()``



  Draws the model in a DSM file with the animation in a DSA file.



  The value of the frame to be drawn is a fixed point value (20.12, or ``f32``).

  If the frame is an integer value there is no interpolation between frames. If

  the frame value is between frames the function will interpolate between them.



- ``DSMA_DrawModelBlendAnimation()``



  Draws the model in the DSM file animated with the data in the specified DSA

  files, at the requested frame, with the requested blending factor between the

  two animations.



  This allows you to merge two animations while you're switching from one to the

  other one, for example.



Future work

-----------



- Smooth shading (only flat shading is supported at the moment).

- Optimize normal commands (if multiple vertices belong to the same joint and

  have the same normal).

- Container files to hold multiple DSM and DSA files.



Thanks to

---------



- **devkitPro**: For helping develop the first version of the library.

  https://devkitpro.org/

- **Blender**: https://www.blender.org/

- **Blender** addon used to generate models:

  https://github.com/KozGit/Blender-2.8-MD5-import-export-addon

- MD5 format information: http://tfc.duke.free.fr/coding/md5-specs-en.html

- Quaternion to matrix conversion: http://www.songho.ca/opengl/gl_quaternion.html

- **DeSmuME**: http://desmume.org/

- **melonDS**: https://melonds.kuribo64.net/