DragonFF: opening a game's own file formats in a modelling tool

What the add-on does

DragonFF is a Blender add-on for the import and export of game files, and the readme is specific about which game and which formats.

At the moment, only the RenderWare files are supported, and support for the other formats is planned. That single sentence sets the scope of the whole project. RenderWare is a game asset format, and the files in it are the ones a game ships: models, textures, collision data, and the map description files. The add-on is a bridge between a file format that only a game engine can read and a modelling application that a person can use.

That is a real piece of work and the reason the add-on is worth looking at even if you have no interest in the particular game. File formats for games are undocumented, reverse engineered, and specific; an importer for one of them is a careful piece of parsing that would otherwise have to be rewritten by every artist who wanted to touch an asset.

And the use case is not only import. The feature list has export for models, for collision files, for textures in a partial and experimental state, and for map files unticked. So somebody can take a model out of the game, work on it in Blender, and put it back, which is the workflow that modding consists of.

The readme is also clear about what it is not yet. The animation file type is not supported at all, and the map file support is marked as partial and experimental, and the texture export is marked the same way. Three different states for three different capabilities, and a reader can tell at a glance which parts of a pipeline are safe to rely on.

The format map

The file type section is a checklist, and reading it as a map of the pipeline is more useful than reading it as a list of features.

Model files are supported both ways, which is the core of the tool. Texture files are supported for import, with export marked partial and experimental. Collision files are supported both ways, including the ones packed inside the model container, which is a nice detail, because a collision file travelling inside the model file is exactly the kind of thing a round trip through a modelling tool would lose if nobody thought about it.

Map files are the ones with the two interesting states. Import is marked partial and experimental, and export is not ticked at all. A map file is the thing that describes the world rather than an object in it, and it has a different shape: a list of entities and their placement rather than a mesh with material effects. It is also the file with the most dependencies on the game's own conventions, since a map is a description of a level rather than an asset, and the same renderer may interpret the same map file differently depending on which parts of it exist.

Animation files are unticked, with no qualifier. That is a bigger absence than the unticked export of the map files, because an animated character without its animation is a static character, and the fact that the readme says so plainly rather than leaving it implied is the kind of clarity that saves somebody a week.

So the shape of the tool is: complete for models, complete for collision, one-way for textures, partial for maps, and absent for animation. A person whose work involves characters would hit that last one immediately, and a person whose work involves props and level dressing would not hit it at all. That is what a format checklist is for.

Material effects, and the parts a generic tool cannot do

The model features section divides into two, and the division is the interesting part.

The first group is the generic stuff that any importer for a game format would need. Skinned mesh support, so that a character arrives with its deformation rig attached rather than as a rigid shape. Multiple texture coordinate sets, which is a requirement rather than a luxury for anything that will be textured more than once. Mass export, so that a whole directory of assets can be written out in one operation rather than one at a time.

The second group is material effects, and it is where the add-on earns its keep. There is environment mapping, where a surface reflects a cube map. There is bump mapping on its own and combined with environment mapping. There is dual texture mapping, where two sets of coordinates drive two textures. And there is texture coordinate animation, again alone and combined with dual mapping.

Look at what that list is. Each of those is a shading technique that the game engine supports and that a modelling application has to represent, and the hard part is not the shading itself but the data: a game format stores these effects in a particular layout, in particular channels, with particular conventions about which texture goes where. An importer that does not understand them produces a model that looks wrong in the game even though it looks right in Blender, and the reverse is true of an exporter that drops them.

Then there is the group of vendor-specific extensions, and it is a list of things no generic tool would know about. A specular material extension. A reflection material extension. A marker for objects that can be broken. A pipeline set, which is the game's own way of grouping assets. A night vertex colour, which is a lighting convention the game applies. And a two-dimensional effects flag.

Each of these is a small, proprietary detail of one engine, and each of them is the kind of thing that makes a general purpose file converter produce subtly broken output. Supporting them is what makes this an importer for a particular game rather than a generic one.

And the reason to build that support as a reusable library rather than as a one-off script is the same in every case: somebody else will need to read and write these files again.

Installing it, and the two ways to get it

There are two install routes, and the readme explains when to use each.

The first is through the modelling tool's own extension gallery, and it applies from a particular version of the application onwards. You open the preferences, go to the extensions tab, search for the add-on, and install it. That route is the ordinary one and it means the add-on is updated with the tool.

The second is a manual install from the repository, and the readme gives two reasons for it: older versions of the application, and getting the newest changes, which it describes as possibly unstable. That parenthetical is the kind of honesty a user appreciates, because the alternative is a manual install that silently gives you a broken build.

The manual steps are four. Download the add-on archive from the latest branch, import it through the add-ons panel in the preferences, enable it, and then use it: the model files come in through the import tab, and the map files come in through a panel in the scene settings.

That last distinction is a small design detail that says something about the tool. Model files are imported through the import machinery, where you would expect them, and the map files, which describe a scene rather than an object, come in through the scene's own settings, because a map is a property of the scene you are building. The add-on has thought about which of its file types is an object and which is a world, and has put the interface accordingly.

And then there is the naming: the add-on appears in the list under a name that includes the game it is for, rather than under the author's own project name. For an add-on that is installed alongside others in the same list, and that is specific to one game, that is the right choice.

The library underneath, and the repository

The last section of the readme is the one that changes the character of the project, because it describes the add-on as a set of reusable modules rather than as a piece of interface.

The scripts have been designed with reusability in mind, and the format module is standalone and can be used with any other Python instance without the need for the application programming interface. That is a significant statement. A Blender add-on normally cannot run outside Blender, because it is full of calls into the host application's interface. If the parsing and writing of these files does not depend on the host, then the same code can run in a build script, in a server, or in a test, and the add-on becomes one consumer of a library rather than the library itself.

The module list follows that structure, and each entry names a file. The model format has its own module, the texture container has its own, the collision format has its own, the map formats share one, and the last one in the list is unticked, which is the texture dictionary format that is not yet written.

And the contributors section names two people and what they brought. One wrote the map importer, which is the partial and experimental part of the format support, and the other wrote the importer for delta morphs, which is a technique in the collision system for deforming geometry. Both are specialist pieces of the format that a general contributor would not have been likely to know.

The repository layout matches the design. There is a library directory holding the format code, separate from the user interface directory and from the operators directory, which in this ecosystem means the code that acts on the scene rather than the code that parses a file. There is the add-on manifest file that the newer extension system reads, and the add-on's own entry point at the root.

So the project is a format library with a graphical front end, which is the right way round. The library can be tested, scripted and reused; the add-on is the part that most people will meet, and it is the smaller half.

Editorial conclusion

DragonFF fits a modder or an artist who needs to work on the assets of a specific game inside a general purpose modelling tool, and who wants the format handling to be a library rather than a set of ad hoc scripts. It does not fit a pipeline that needs every file type, because animation and map export are not implemented. Verify first which of the five file types you actually need, since the readme marks two of them as partial, that the version of the modelling tool you have is one the add-on supports, since the packaged extension route needs a recent release, and that you can accept the manual install route if you need the newest changes, because the readme describes that path as possibly unstable.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Parik27/DragonFF on GitHub
4. README
5. Releases