v50 Steam/Premium information for editors
  • v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
  • Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.

Difference between revisions of "Graphics token"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(Added some tokens using the info gathered on [https://gitlab.com/df-modding-tools/df-raw-language-server/ the DF language server])
(Addition of basic how-to's for creature graphics.)
Line 1: Line 1:
 
{{Quality|Unrated}}
 
{{Quality|Unrated}}
 
{{av}}
 
{{av}}
 +
{{old}}
 
{{Modding}}
 
{{Modding}}
{{old}}
 
  
The <code>[OBJECT:GRAPHICS]</code> [[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 are listed below; the list will expand as the tokens are discovered and understood:
+
The <code>[OBJECT:GRAPHICS]</code> [[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 <code>\<mod_id>\graphics\images</code> folder
 +
# A "tile_page_name.txt" in the <code>\<mod_id>\graphics</code> folder
 +
# A "graphics_type_name.txt" in the <code>\<mod_id>\graphics</code> 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 file]]s, 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 <code>\graphics\images</code> 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 <code>[TILE_DIM:32:32]</code> 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 <code>[PAGE_DIM_PIXELS:<x dim>:<y dim>]</code> 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 <code>[OBJECT:GRAPHICS]</code> 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 <code>DEFAULT</code> for the simplest graphics.
 +
* ''creature id'': The [[Creature token|Creature ID]] the graphics represent.
 +
* ''tile page identifier'': The Internal ID of the image defined in [[#Tile Page|tile page]].
 +
* ''x position'': The x position (left&rarr;right) of the image in tiles counting from 0.
 +
* ''y position'': The y position (top&rarr;bottom) of the image in tiles counting from 0.
 +
* ''color type'': (optional) Frequently replaced with <code>AS_IS</code> in vanilla [[Raw|RAW]]s. ColorTypeEnum{{cite|DF language server|https://gitlab.com/df-modding-tools/df-raw-language-server/-/blob/dev/df_ls_structure/src/objects/graphics.rs}}
 +
* ''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|Caste ID]] of the caste whose graphics are being specifically defined.
 +
 
 +
Creature caste graphics only accept <code>MALE</code> and <code>FEMALE</code> 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 <code>LARGE_IMAGE</code> 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.
  
__NOTOC__
+
Large images and small images can be used within the same <code>CREATURE_GRAPHICS</code> or <code>CREATURE_CASTE_GRAPHICS</code> definition, and in fact it is often useful to include a single tile image to act as a {{token|LIST_ICON|g}} for menus.
  
{{clear}}
 
{{alphabetical TOC|style=margin: 1em auto;}}
 
  
==Creature Graphics Tokens==
+
==== Conditions ====
The below tokens are for CREATURE_GRAPHICS objects
+
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 <code>CREATURE_GRAPHICS</code> and <code>CREATURE_CASTE_GRAPHICS</code>.
  
 
{| {{prettytable}}
 
{| {{prettytable}}
|- bgcolor="#ddd"
+
|- bgcolor="#dddddd"
! width="20%" | Token
+
! Condition
! width="20%" | Arguments
+
! Accepts<br>Secondary
! width="50%" | Description
+
! Description
 +
|-
 +
| {{text anchor|DEFAULT}} || No || The default condition that will be displayed unless overwritten by a more specific one below.
  
 
|-
 
|-
| {{text anchor|ANIMATED}}
+
| {{text anchor|CHILD}} || Yes || Will only be displayed if the creature has a {{token|CHILD|c}} or {{token|BABY|c}} and is younger than one of those ages.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
 
|-
 
|-
| {{text anchor|CORPSE}}
+
| {{text anchor|ANIMATED}} || Yes || Displayed if the creature is risen from the dead (has {{token|NOT_LIVING|c}} or {{token|OPPOSED_TO_LIFE|c}}){{verify}}
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
 
|-
 
|-
| {{text anchor|DEFAULT}}
+
| {{text anchor|CORPSE}} || Yes || Displayed as soon as the creature dies.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
 
|-
 
|-
| {{text anchor|LIST_ICON}}
+
| {{text anchor|TRAINED_HUNTER}} || Yes || Shown for hunting-trained versions of this creature.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position,
 
*ColorTypeEnum (according to the [https://gitlab.com/df-modding-tools/df-raw-language-server/-/blob/dev/df_ls_structure/src/objects/graphics.rs DF language server], unclear what it means)
 
|
 
  
 
|-
 
|-
| {{text anchor|SKELETON}}
+
| {{text anchor|TRAINED_WAR}} || Yes || Shown for war-trained versions of this creature.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
 +
|-
 +
| {{text anchor|LIST_ICON}} || Unknown || Displayed in menus. Useful for large images that would extend beyond the menu boxes otherwise/
  
 
|-
 
|-
| {{text anchor|SKELETON_WITH_SKULL}}
+
| {{text anchor|SKELETON}} || Unknown || Decayed remains of the creature.{{verify}}
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
|}
+
|-
 +
| {{text anchor|SKELETON_WITH_SKULL}} || Unknown || Decayed remains of the creature with a skull.{{verify}}
  
=== Vermin ===
+
|-
Tokens for vermin graphics
+
| {{text anchor|VERMIN}} || Unknown || Necessary for defining graphics that use the tokens below.{{verify}}
  
{| {{prettytable}}
+
|-
|- bgcolor="#ddd"
+
| {{text anchor|VERMIN_ALT}} || Unknown || Image cycles every 1 second.
! width="20%" | Token
 
! width="20%" | Arguments
 
! width="50%" | Description
 
  
 
|-
 
|-
| {{text anchor|VERMIN}}
+
| {{text anchor|SWARM_SMALL}} || Unknown || For swarming vermin like [[fly|flies]] and [[fairy|fairies]] in small groups.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
 
|-
 
|-
| {{text anchor|VERMIN_ALT}}
+
| {{text anchor|SWARM_MEDIUM}} || Unknown || For swarming vermin like [[fly|flies]] and [[fairy|fairies]] in medium-sized groups.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| Image cycles every 1 second.
 
  
 
|-
 
|-
| {{text anchor|SWARM_SMALL}}
+
| {{text anchor|SWARM_LARGE}} || Unknown || For swarming vermin like [[fly|flies]] and [[fairy|fairies]] in large groups.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| For swarming vermin like [[fly|flies]] and [[fairy|fairies]].
 
  
 
|-
 
|-
| {{text anchor|SWARM_MEDIUM}}
+
| {{text anchor|LIGHT_VERMIN}} || Unknown || For [[firefly|fireflies]] etc. Does not replace {{token|VERMIN|g}}.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| For swarming vermin like [[fly|flies]] and [[fairy|fairies]].
 
  
 
|-
 
|-
| {{text anchor|SWARM_LARGE}}
+
| {{text anchor|LIGHT_VERMIN_ALT}} || Unknown || Like {{token|VERMIN_ALT|g}} for [[firefly|fireflies]] etc.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| For swarming vermin like [[fly|flies]] and [[fairy|fairies]].
 
  
 
|-
 
|-
| {{text anchor|LIGHT_VERMIN}}
+
| {{text anchor|LIGHT_SWARM_SMALL}} || Unknown || Like {{token|SWARM_SMALL|g}} for [[firefly|fireflies]] etc in small groups.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| For [[firefly|fireflies]] etc.
 
  
 
|-
 
|-
| {{text anchor|LIGHT_VERMIN_ALT}}
+
| {{text anchor|LIGHT_SWARM_MEDIUM}} || Unknown || Like {{token|SWARM_LARGE|g}} for [[firefly|fireflies]] etc in large groups.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| Like {{token|VERMIN_ALT|g}} for [[firefly|fireflies]] etc.
 
  
 
|-
 
|-
| {{text anchor|LIGHT_SWARM_SMALL}}
+
| {{text anchor|LIGHT_SWARM_LARGE}} || Unknown || Like {{token|SWARM_LARGE|g}} for [[firefly|fireflies]] etc.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| Like {{token|SWARM_SMALL|g}} for [[firefly|fireflies]] etc.
 
  
 
|-
 
|-
| {{text anchor|LIGHT_SWARM_MEDIUM}}
+
| {{text anchor|REMAINS}} || Unknown || Vermin corpses.
|  
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
| Like {{token|SWARM_MEDIUM|g}} for [[firefly|fireflies]] etc.
 
  
 
|-
 
|-
| {{text anchor|LIGHT_SWARM_LARGE}}
+
| {{text anchor|HIVE}} || Unknown || Vermin hives.
|  
+
|}
*tile page ID,
+
 
*grid x position,
+
 
*grid y position
+
=== Layered Graphics ===
| Like {{token|SWARM_LARGE|g}} for [[firefly|fireflies]] etc.
+
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 <code>DEFAULT</code> for the simplest graphics.
 +
* ''creature token'': The [[Creature token|Creature ID]] the graphics represent.
 +
* ''tile page identifier'': The Internal ID of the image defined in [[#Tile Page|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 <code>TILE_GRAPHICS_RECTANGLE</code> 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-{{token|FEATURE_BEAST|c}} creatures.{{verify}}
  
|-
 
| {{text anchor|REMAINS}}
 
|
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
|-
+
== Item Graphics ==
| {{text anchor|HIVE}}
+
Item graphics can also be defined, but are mostly hardcoded. This section of the wiki needs to be fleshed out.
|
 
*tile page ID,
 
*grid x position,
 
*grid y position
 
|
 
  
|}
 
  
 
==See Also==
 
==See Also==
 
*[[Palette token]]
 
*[[Palette token]]
*[[Tile page token]]
 
 
*[[Body detail plan token]]
 
*[[Body detail plan token]]
 
*[[Body token]]
 
*[[Body token]]

Revision as of 13:46, 6 January 2023

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:

  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

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.


See Also