Graphics token

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

v50.14 · v0.47.05

This article is about the current version of DF.
Note that some content may still need to be updated.

The [OBJECT:GRAPHICS] token 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. These tokens, and explanations on how to use them, are listed below; the list will expand as the tokens are discovered and understood.

Making custom graphics requires multiple interacting files to function:

An 8bit RGBA (sometimes called 32bit) "imagename.png" in the \<mod_id>\graphics\images folder
A "tile_page_name.txt" in the \<mod_id>\graphics folder
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

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, displayed by default for all conditions the creature is in:

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

condition: The state the creature needs to be in for this image to be displayed. Use DEFAULT for the simplest graphics.
creature id: The Creature ID the graphics represent.
tile page identifier: The Internal ID of the image defined in tile page.
x position: The x position (left→right) of the image in tiles counting from 0.
y position: The y position (top→bottom) of the image in tiles counting from 0.
color type: (optional) 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.

Caste Graphics

[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 specifically defined.

Creature caste graphics only accept MALE and FEMALE as caste id's even in custom 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.

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.

Conditions

Different graphics can be defined for the same creature based on some properties about it. Below is a list of all conditions that can be used for CREATURE_GRAPHICS and CREATURE_CASTE_GRAPHICS.

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 has a `[CHILD]` or `[BABY]` and is younger than one of those ages.
ANIMATED	Yes	Displayed if the creature is risen from the dead (has `[NOT_LIVING]` or `[OPPOSED_TO_LIFE]`)^[Verify]
CORPSE	Yes	Displayed as soon as the creature dies.
TRAINED_HUNTER	Yes	Shown for hunting-trained versions of this creature.
TRAINED_WAR	Yes	Shown for war-trained versions of this creature.
LIST_ICON	Unknown	Displayed in menus. Useful for large images that would extend beyond the menu boxes otherwise/
SKELETON	Unknown	Decayed remains of the creature.^[Verify]
SKELETON_WITH_SKULL	Unknown	Decayed remains of the creature with a skull.^[Verify]
VERMIN	Unknown	Necessary for defining graphics that use the tokens below.^[Verify]
VERMIN_ALT	Unknown	Image cycles every 1 second.
SWARM_SMALL	Unknown	For swarming vermin like flies and fairies in small groups.
SWARM_MEDIUM	Unknown	For swarming vermin like flies and fairies in medium-sized groups.
SWARM_LARGE	Unknown	For swarming vermin like flies and fairies in large groups.
LIGHT_VERMIN	Unknown	For fireflies etc. Does not replace `[VERMIN]`.
LIGHT_VERMIN_ALT	Unknown	Like `[VERMIN_ALT]` for fireflies etc.
LIGHT_SWARM_SMALL	Unknown	Like `[SWARM_SMALL]` for fireflies etc in small groups.
LIGHT_SWARM_MEDIUM	Unknown	Like `[SWARM_LARGE]` for fireflies etc in large groups.
LIGHT_SWARM_LARGE	Unknown	Like `[SWARM_LARGE]` for fireflies etc.
REMAINS	Unknown	Vermin corpses.
HIVE	Unknown	Vermin hives.

Layered Graphics

Layered graphics are a method for displaying overlapping body parts, equipment, clothing, professions, hairstyles.. etc.

Forgotten Beast Graphics

Forgotten beast graphics define layered graphics based on which body parts are present in each procedurally-generated forgotten beast.

   [TILE_GRAPHICS_RECTANGLE:<tile page id>:<x1>:<y1>:<x2>:<y2>:<body_rcp token>]

condition: The state the creature needs to be in for this image to be displayed. Use DEFAULT for the simplest graphics.
creature token: The Creature ID the graphics represent.
tile page identifier: The Internal ID of the image defined in tile page.
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.

The TILE_GRAPHICS_RECTANGLE token displays a large image with the upper left corner being defined by <x1>, <y1> and the lower right corner defined by <x2>, <y2>. The <body_rcp_token> is a conditional token that causes the graphics for each layer to be displayed only when the forgotten beast has that particular body part.^[Verify]

There is not currently a way to use procedurally defined graphics like this for non-[FEATURE_BEAST] creatures.^[Verify]

Item Graphics

Item graphics can also be defined, but are mostly hardcoded. This section of the wiki needs to be fleshed out.