How to manually install Dwarf Fortress tileset

I'm gonna attempt to save us all some frustration and emphasize the fact that I'm not asking about LNP or ANY other similar pre-packaged tool.

I cannot find a single reference anywhere that walks through the process of manually installing a new tileset. The DF documentation is pretty sparse and I haven't been able to successfully install any tileset by following it. And every other reference, tutorial, book, or video that I've found all points to using LNP which I'm not asking about.

The best I can tell, it seems like there are actually multiple (in fact, many) different files/settings that need to be modified to use a given tileset. And to add further complication, it seems like perhaps not all of them need to be modified, depending on various factors (like current resolution). But I can find no reference that documents what modifications need to be made, what the various modifications do (so that I can decide if I need to make that particular change), etc. Or I could be totally wrong about all of that.

How do I manually install a tileset in just vanilla, out-of-the-box Dwarf Fortress?

Solution 1:

As an addendum to Raven's answer:

Dwarf fortress has four different values for font and tileset files. That is because it reuses the same symbols for both text, displaying tiles, and data. However, DF is smart enough to be able to use a tile set for only its graphics, not its text, 'mostly'. It's written for the use of the standard windows-1252 encoding (also known as latin-1 or IBM CP 437.). The reason it can somewhat separate things is because it tends to use the ASCII set for text and the Extended set for "graphics".

Here's what each of the four font value options mean:

'Somewhat' fixing the issue:

FONT

This sets the replacement images for the 256 font characters. You can and should set this to a text font file (i.e. the default), not your tileset graphics. This prevents your tileset graphics from overwriting characters such as 0 or .

If you prefer the graphics for these tiles over somewhat less legible text, you can set this to your graphics file. Be sure to set the TRUETYPE option to YES (see below).

FULLFONT

This sets the replacement images for the 256 characters when the game is in fullscreen. It's usually the same as FONT.

TRUETYPE

This should be set to YES. This allows for the override of your tileset font and instead the game will use data/art/font.ttf for all text outside the game area, reducing the text corruption issues somewhat.

Details

Using the above settings with regular DF will get you a game that is somewhat readable, but has a few quirks:

Graphics font packs usually leave the letters a-zA-Z0-9 alone while modifying characters such as éáö&. This leaves you with a few graphics in place of text, and a little text in place of graphics, but overall the game will be legible and work.

Why you are experiencing complete Mojibake, is because you are likely using a version of the tileset graphics meant for TWBT. (See more about this below). A version meant for the regular game leaves most of the alphabet alone to keep text legible.

First, sometimes extended characters are used in text (dwarven names and item qualities come to mind). These are then replaced with graphics.

Second, sometimes regular characters are used for creatures and so on. These still display as letters.

A simple tileset mod cannot fix these two issues by itself. But partially installing one for just the extended characters makes your text more legible.

The other two options [GRAPHICS_FULLFONT] and [GRAPHICS_FONT] are to be used if you want to use a creature graphics pack alongside your tileset graphics.

Creature graphics

Graphics tilesets can also be added to dwarf fortress to have more than 256 symbols available to you, and thus to present more detail in game views. They are additional image files that contain all creatures in the game, in various states. Other things currently have no graphic set data defined for them, and still have to use the regular tileset.

They are often made to be combined with a tileset. You can mix and match, as long as you use the same pixel size for a square. (So any 16x16 tile set can be combined with any 16x16 creature graphics set).

To install such a set manually, first set the GRAPHICS = yes option in init.txt. Then copy in the set's /raw/graphics folder. This contains text files telling the game where to find which graphic, as well as tile sheets. The game will automatically read all text files in this folder. The text files create in-game data objects known as tile pages with arbitrary labels pointing to the files, and add the tile page index to a creature to give it its graphic. An example to illustrate (taken from Phoebus graphics):

[TILE_PAGE:PHOEBUS_DD]
  [FILE:doren/042.png]
  [TILE_DIM:16:16]
  [PAGE_DIM:12:5]

This creates a new tile page called PHOEBUS_DD for use with dwarfs. It can be found in the file /raw/graphics/doren/042.png. The tiles in it are 16x16 pixels big, and there are 60 tiles in the file: it is 12 wide and 5 tall. Then, to assign a creature to the set, you use:

[CREATURE_GRAPHICS:DWARF]
  [SAGE:PHOEBUS_DD:0:0:AS_IS:DEFAULT]

This tells the game that the top-left most image (the index [0,0]) is of an adult dwarf which currently has the "Sage" profession.

You can find a list of (a few of the) graphics tileset at the graphics tileset repository. Also see What is the different between a character set and a graphic set? for more information.

DFHack to the rescue

If you're willing to try something a little more advanced...

Thankfully, many others have found these workarounds not fully satisfying and someone has written a DFhack plugin aptly named Text Will Be Text. Also see its repository page.

This plugin will override Dwarf fortress so that it can use the full text set (both ASCII and Extended) for both [FONT] and [FULLFONT]. It will use [FONT] for text, but it will use [FULLFONT] for tiles. This should resolve all corruption issues, but is a little bit trickier to install. Be sure to read the linked thread for instructions.

Its repository may be out of date (it currently is, just checked). You would have to rebuild the source against current DFhack (I.e. dive into the C++ code and fix it). Thankfully, someone seems to have done this for you, with an unofficial port for the latest DFhack.

If dwarf fortress updates further from here, then have a look at the changes Thurin made. If you look at the DFhack source you should be able to find the new offsets required to make this plugin work again.

Make sure that DF, DFhack, and TWBT are all compatible versions. If not, your game is likely to be unstable and crash when you least want it to. Or, more likely, version checks will fire and DFHack or TWBT will refuse to even run.

Additional resources

This forum thread about installing fonts may be worth reading
Here's another one where this problem is detailed
A full list of things creature graphic sets can provide can be found on the Wiki

Solution 2:

The DF Wiki has you covered!

Download the tileset via right-click-save-as on the tileset. The tileset is just an image.
Verify that the tileset is a 24-bit PNG file with transparent background. In case you need to convert it, do NOT just change the extension to .bmp or .png; you must use a program like MS paint to save it properly.
Put it in the data/art directory of your Dwarf Fortress installation.
Open data/init/init.txt
There are 4 values you can change: [FULLFONT], [FONT], [GRAPHICS_FONT], and [GRAPHICS_FULLFONT]. Usually you just set all 4 to the same filename of the tileset you just downloaded ([FONT:mytileset.png] for example).
[FULLSCREENX:800] and [FULLSCREENY:600] set your resolution, but it is recommended to let the game decide that automatically by setting it to 0; Similarly, [WINDOWEDX:800] and [WINDOWEDY:600] denote your windowed resolution in pixels (but in tiles if set below a value of 256).
It is also recommended you keep [BLACK_SPACE:YES] to prevent stretching of the graphics.
Save the .txt file, then you're ready to play!