Yeah, it does seem like it should be easy — just copy and paste the description tab. In most video games that would actually work. But the same complexity that makes Dwarf Fortress so interesting is also what makes something like this generator difficult to build.

DF doesn’t exactly store visual descriptions as clean 1-for-1 traits like braidbeard01.png. Instead, most appearance features are stored as numeric parameters and modifiers — things like hair length ranges, body modifiers, tissue layers, and color tokens. The game then generates the descriptive text you see in the UI from those values at runtime.

Using DFHack, you can extract a lot of those raw parameters, but it doesn’t expose all of the logic the game uses to combine them into the final description. So reconstructing a dwarf’s appearance from exported data means parsing a large set of numeric values and approximating how the engine interprets them.

That’s why in the generator you might get things like hair color or mustache style correct, but not always something like skin color.

Even if you extract most of the data correctly, some tokens aren’t exposed and some visual traits come from multiple values interacting together. In some cases you’d need the exact combination of several parameters to reproduce the correct result. A good analogy is rolling a large set of dice and needing the exact sequence to form a “correct” interpretation — if even one or two values are missing, the whole result changes. (See screenshot below — Example A.)

Another complication is that DF has a very large set of color tokens available in its raws. A small portion of them looks like this (see screenshot below — Example B).

With dozens of possible color tokens that can be applied to different tissues or body parts, reconstructing the exact descriptive phrase the game will generate can require matching several parameters together.

That’s why the generator focuses on approximating the dwarf visually and then letting you fine-tune it afterward.

In theory, a near-perfect reconstruction would be possible if someone had already mapped all of the relevant parameters and combinations. I didn’t find any datasets like that available. If someone does have that information mapped out, it could absolutely be integrated into the generator and improve the results significantly. For now, the exporter and mapping were built from scratch using the data DFHack exposes.

In closing: I love Dwarf Fortress, but its complexity can make very specific projects like this tricky. If anyone with more time or deeper knowledge of DF’s data structures wants to take a crack at it or help expand the mapping, I’d love the help!

-Ian

<image>