Graphic set

(For an overview of graphics in DF, see Graphics)

(For user-created creature graphics sets, see Graphics set repository.)

A graphic set is an additional tileset for objects. While this is eventually planned for all objects in game, currently only creatures can assigned to graphic sets. Graphic sets are placed in raw/graphics (as well as the raw folder of each save); A corresponding text file assigns tiles to objects.

Documentation

The graphic sets themselves are placed into subfolders. It is recommended that they have the same tile size as the main tileset, but the number of tiles and their spatial arrangement doesn't matter (see Notes for details). All creatures can have separate graphics assigned to their adult and child states, undead, and their -men and giant variants. In addition, the major Civilizations can have separate graphics for all professions (such as miner, mason, caravan guard, and ghost). You can assign one graphic to several creatures/states, and you can set each tile to either be displayed as it appears or let the game color them. Vermin and different genders cannot have separate graphics assigned to them.

Text File Syntax

A Graphic set needs a text file that tells the game which tile is used for which creature. You can use separate text files for each graphic set, or a single one for several. Each text file consists of a header, one or more graphic set definitions (called "TILE_PAGE") and several creature graphics entries, each of which has subentries for professions.

The structure of a typical text file would look like this:

• Header
• Tile page definition
  • Creature graphic entry
    • profession subentry
    • more
    • profession
    • subentries
  • next creature
    • with
    • more
    • professions
• new tile page definition
  • a creature
    • with adult
    • and child graphics
  • and another creature
    • adult
    • child

Below is an example of such a file.

graphics_mygraphics ← The first line of the header. You'll be saving the text document as this name (graphics_mygraphics.txt) 
                            This name should match the folder name you will be using in "raw/graphics".

[OBJECT:GRAPHICS] 
This concludes the header. Each graphic set text file needs to contain these lines.
------------------------------
below are dwarves ← text outside brackets gets ignored. You can use it for comments and organizing your file visually with lines 
 
[TILE_PAGE:MYDWARVES] ← Here you are defining properties of a single graphic set image. The title MYDWARVES will be used in creature graphic entries to refer to that graphic set. The title doesn't have to match any creature, folder, or image name. 
       [FILE:mygraphics/mydwarves.png] ← The subfolder where the graphic set is located (relative to this text file) and its filename, including the file extension. 
       [TILE_DIM:16:16] ← Height:Width - Pixels per tile, so DF knows where one tile ends and another begins
       [PAGE_DIM:5:3] ← Width:Height - Tiles per image and how they're arranged in rows and columns. 

		This concludes the first TILE_PAGE definition. 
		Next are the creature graphic entries. Syntax is: [Profession:TILE_PAGE:X:Y:Color:State] 
		X and Y are the coordinates of the tile on the image. More information below. 
[CREATURE_GRAPHICS:DWARF] ← The value (DWARF in this case) is the name the creature has in the raws. This NEEDS to be spelled correctly.
       [DEFAULT:MYDWARVES:0:0:ADD_COLOR:DEFAULT]
                                  ↑  The ADD_COLOR value tells DF to give the tile the same colors as the default graphic 
       [STANDARD:MYDWARVES:1:0:AS_IS:DEFAULT]
                                  ↑ AS_IS takes the tile as it is. Most likely this is the setting you want
       [MINER:MYDWARVES:2:0:AS_IS:DEFAULT]
                  ↓ We defined the tile page above. it refers to the image mydwarves.png 
       [CHILD:MYDWARVES:3:0:AS_IS:DEFAULT]
       [BABY:MYDWARVES:4:0:AS_IS:DEFAULT]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
humans 

[TILE_PAGE:MYHUMANS] ← The next TILE_PAGE definition. You could put that (and its creature graphic entries) in a separate text file, but it would have to contain its own header.
       [FILE:Other_Graphics/humans.png] ← This file is in another subfile
       [TILE_DIM:16:16]
       [PAGE_DIM:1:4] 

[CREATURE_GRAPHICS:HUMAN]
       [DEFAULT:MYHUMANS:0:0:AS_IS:DEFAULT]	
    Notes can go here too.        
       [SWORDSMAN:MYHUMANS:0:1:AS_IS:DEFAULT]
       [RECRUIT:MYHUMANS:0:2:AS_IS:ADVENTURER] ← An ADVENTURER with no weapons
       [SWORDSMAN:MYHUMANS:0:3:AS_IS:ADVENTURER] ← An ADVENTURER with a sword
==============================
animals 

[TILE_PAGE:MYANIMALS]
       [FILE:Other_Graphics/animals.bmp] ← Pictures can be in .BMP format, too.
       [TILE_DIM:16:16]
       [PAGE_DIM:6:2] 

[CREATURE_GRAPHICS:DOG]
       [DEFAULT:MYANIMALS:0:0:AS_IS:DEFAULT]
       [CHILD:MYANIMALS:1:0:AS_IS:DEFAULT]
       [TRAINED_HUNTER:MYANIMALS:4:0:AS_IS:DEFAULT] ← TRAINED_HUNTER profession only works with animals that have the [TRAINABLE] or [TRAINABLE_HUNTING] tag.
       [TRAINED_WAR:MYANIMALS:5:0:AS_IS:DEFAULT] ← TRAINED_WAR profession only works with animals that have the [TRAINABLE] or [TRAINABLE_WAR] tag.
[CREATURE_GRAPHICS:CAT]
       [DEFAULT:MYANIMALS:0:1:AS_IS:DEFAULT]

The PAGE_DIM value in the TILE_PAGE section defines how many columns and rows a given TILE_PAGE (graphic set) has. The first value is the X axis (or "width"), the second value the Y axis ("height"). The origin (0,0) is at the top left. This is how the coordinates would work with the image mydwarves.png from the example above:

0:0	1:0	2:0	3:0	4:0
0:1	1:1	2:1	3:1	4:1
0:2	1:2	2:2	3:2	4:2

The position of the dwarven child graphic from the example above ([CHILD:MYDWARVES:3:0:AS_IS:DEFAULT]) is shown in bold.

Note that the coordiantes start at 0, not 1. So, the last column in a 5 tile wide image is at 4, not at 5.

Notes

The total number of tiles in a sheet cannot number more than 1024, regardless of how big (18x18) or how small (8x12) each tile is. Thus, a sheet that has its graphics organized into 22 rows and 44 columns works fine (as 22x44=968 which is less than 1024. However, a sheet that has 24 rows and 44 columns (24x44=1056) will not work.