Graphics

!!UNKNOWN!!  · xTATTEREDx  · +FINE+  · *SUPERIOR*  · ≡EXCEPTIONAL≡  · ☼MASTERWORK☼

v53.08 · v0.47.05 This article is about the current version of DF. Note that some content may still need to be updated. More Info · V

For a list of all Premium graphics tokens and basic usage, see Graphics token.

For a repository of all Classic tilesets used in DF, see Tileset repository.

For details on creating Classic tilesets, see Tileset repository.

The graphics system in v50 is still being reverse engineered. It is a custom solution which appears to involve compositing graphics sets directly in C++ before texmapping them to SDL. This blitting approach is software rendered and so largely doesn't use hardware acceleration on graphics cards. This system means that despite graphics sets supporting rudimentary animation, there is no traditional sprite mapping, which places extensive limits on the types of graphics that are possible. While the number of user editable graphics sets has increased significantly in v50, many game elements are still hard coded graphics sets, or using a tileset over the older style graphics from classic DF.

Premium Graphics

For a list of all Premium graphics tokens and basic usage, see Graphics token.

The [OBJECT:GRAPHICS] object defines the use of various tile-based graphics in the game. As of version 50.01, graphics tokens have been greatly expanded to accommodate the release of the Steam & Itch premium version. This section is a basic description of how to define various types of graphics.

Making custom graphics requires multiple interacting files to function:

1. An 8bit RGBA (sometimes called 32bit) "imagename.png" in the \<mod_id>\graphics\images folder
2. A "tile_page_name.txt" in the \<mod_id>\graphics folder
3. A "graphics_type_name.txt" in the \<mod_id>\graphics folder

Mods can reuse any graphics loaded ahead of them (including vanilla) by using the same tile page token.

Tile Page

Tile pages link image files to a tile page token so they can be referenced by the graphics file. Just like all other Raw files, Tile Pages must be defined from within a properly named "tile_page_<name>.txt" file and follow:

tile_page_<name>

[OBJECT:TILE_PAGE]

After the object type is defined as above, any number of tile pages can be defined according to the format below.

  [TILE_PAGE:<tile page identifier>]
     [FILE:images/imagename.png]
     [TILE_DIM:<tile x dim>:<tile y dim>]
     [PAGE_DIM_PIXELS:<page x dim>:<page y dim>]

• tile page identifier: The Internal ID being created for the image.
• imagename.png: The file name of the 8bit RGBA (sometimes called 32bit) in the \graphics\images folder of the mod.
• tile x dim: The width of each tile in pixels (usually 32).
• tile y dim: The height of each tile in pixels (usually 32).
• page x dim: The width of the image file in pixels.
• page y dim: The height of the image file in pixels.

Known issues:

• Currently it is only recommended to use [TILE_DIM:32:32] as only the upper left 32x32 pixels are displayed on tiles defined larger, and smaller tiles are displayed starting from the upper left of each in-game square (individually by tile with large graphics) rather than centered and bottom justified as might be expected.
• It is important that the [PAGE_DIM_PIXELS:<x dim>:<y dim>] matches the size of the referenced image exactly - as the game will stretch tile pages with a dimension larger than the actual image by inserting blank lines, and a tile page smaller than the image will cause a crash to desktop.

Creature Graphics

For a list of all known creature graphics tokens, see Graphics token#Creature Graphics..

Creature graphics are found within graphics_creature_x files (such as graphics_creature_domestic or graphics_creature_layered). All graphics files must begin with the file name, followed by the [OBJECT:GRAPHICS] token that tells the game that the file contains graphics definitions.

Basic Graphics

The most basic form of creature graphics is a single tile, defined below:

[CREATURE_GRAPHICS:<creature id>]
   [<condition>:<tile page identifier>:<x position>:<y position>:<color type>:<secondary condition>]

• condition: The condition the creature needs to be in for this image to be displayed. Use DEFAULT for generic graphics.
• creature id: The Creature ID of the creature the graphics represent.
• tile page identifier: The Internal ID of the image defined in the Tile Page.
• x position: The x position of the graphic to be displayed in tiles counting from 0 (left→right).
• y position: The y position of the graphic to be displayed in tiles counting from 0 (top→bottom).
• color type: (optional) Uncertain function, frequently replaced with AS_IS in vanilla RAWs. ColorTypeEnum^[1]

• secondary condition: (optional) An additional condition that must be satisfied for the image to be displayed.

When the condition [DEFAULT] is used, this graphic will be displayed for the creature in all conditions unless additional, more specific conditions are also defined.

Basic Conditions

Different graphics can be defined for the same creature based on some properties about it. Below is a list of the most common creature conditions tokens.

Condition	Accepts Secondary	Description
[DEFAULT]	No	The default condition that will be displayed unless overwritten by a more specific one below.
[CHILD]	Yes	Will only be displayed if the creature is a [CHILD] or [BABY] and is younger than one of those ages.
[ANIMATED]	Yes	Displayed if the creature is raised from the dead, although it is not known how this is decided. Raised status is not related to having a syndrome with the class from [CONDITION_SYN_CLASS] or from having [NOT_LIVING]/[OPPOSED_TO_LIFE].
[CORPSE]	Yes	Displayed as soon as the creature dies.
[LIST_ICON]	Unknown	Displayed in menus. Useful for large images that would extend beyond the menu boxes otherwise.

Caste Graphics

Creature caste graphics allow a simple alternative to Layered Graphics to represent males and females of a creature with different images.

[CREATURE_CASTE_GRAPHICS:<creature id>:<caste id>]
   [<condition>:<tile page identifier>:<x position>:<y position>:<color type>:<secondary condition>]

• caste id: The Caste ID of the caste whose graphics are being defined.
• All other parameters are identical to basic graphics.

Creature caste graphics only accept MALE and FEMALE as caste id's even in creatures that have more than two castes.

Large Graphics

The only difference between graphics for large creatures and small creatures is the addition of LARGE_IMAGE and additional coordinates to the line below:

   [<condition>:<tile page identifier>:LARGE_IMAGE:<x1>:<y1>:<x2>:<y2>:<color type>:<secondary condition>]

• LARGE_IMAGE: This tag allows a rectangular image with multiple tiles to be defined by its upper left and lower right tiles. Valid for 1x1 - 3x2 tiles.
• x1: The x position of the upper left tile counting from 0 from the left of the tile page.
• y1: The y position of the upper left tile counting from 0 from the top of the tile page.
• x2: The x position of the lower right tile.
• y2: The y position of the lower right tile.
• All other parameters are identical to basic graphics.

Large images and small images can be used within the same CREATURE_GRAPHICS or CREATURE_CASTE_GRAPHICS definition, and in fact it is often useful to include a single tile image to act as a [LIST_ICON] for menus.

Statue Graphics

Statue graphics are the generic images placed on top of a pedestal whenever a creature is the primary subject of a statue. The image is implied to occupy multiple tiles, and all examples in vanilla are 1x2 vertical rectangles. Statue graphics are defined as below:

[STATUE_CREATURE_GRAPHICS:<creature id>]
       [DEFAULT:STATUES_LAYERED:<x1>:<y1>:<x2>:<y2>]

• creature id: The Creature ID the graphics represent.
• x1: The x position of the upper left tile counting from 0 from the left of the tile page.
• y1: The y position of the upper left tile counting from 0 from the top of the tile page.
• x2: The x position of the lower right tile.
• y2: The y position of the lower right tile.

Layered Graphics

Layered graphics are a method for displaying overlapping body parts, equipment, clothing, professions, hairstyles.. etc. They allow much more freedom in conditions than normal basic graphics, and they allow combinations of many graphical variations within the same creature to give your graphics more personality and display more information about the individuals. All layered graphics started as shown below:

[CREATURE_GRAPHICS:<creature id>]
	[LAYER_SET:<condition>]

• creature id: The Creature ID of the creature the graphics represent.
• condition: The condition the creature needs to be in for this set of layers to be displayed.

Once you start defining a Layer Set, you can begin adding individual layers from the bottom up to create your final image. For example, if you want to draw a helmet being worn on a head, you would define the head layer first, then define the helmet layer. Layers are defined according to this format:

[LAYER:<layer name>:<tile page id>:<x position>:<y position>:<color type>]
	[<layer condition(s)>]

• layer name: The internal name of the layer. No known function at this time, but using a descriptive label is recommended.
• tile page identifier: The Internal ID of the image defined in the Tile Page.
• x position: The x position of the graphic to be displayed in tiles counting from 0 (left→right).
• y position: The y position of the graphic to be displayed in tiles counting from 0 (top→bottom).
• LARGE_IMAGE:x1:y1:x2:y2: (optional) Allows a multiple tile image to be displayed. Replaces <x position>:<y position>.
• color type: (optional) Uncertain function, frequently replaced with AS_IS in vanilla RAWs. ColorTypeEnum