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 "Modding"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(use main ns alias)
(→‎Selecting and Cutting: Added note that a CUT operation does not require a prior SELECT operation.)
(69 intermediate revisions by 24 users not shown)
Line 1: Line 1:
−
{{Quality|Exceptional|14:13, 7 November 2013 (UTC)}}
+
{{migrated article}}
 +
{{Quality|Fine}}
 
{{av}}
 
{{av}}
−
{{catbox|DF2014:Modding}}
+
{{For/see|a list of Dwarf Fortress mods|[[List of mods]]}}
 +
{{Modding}}
 +
'''Modding''', or creating [[mod]]s, refers to modifying the behavior of the base game (vanilla). ''Dwarf Fortress'' is remarkably moddable.
 +
 
 +
== Resource Overview==
 +
[[File:modding_icon.png|120px|right]]This section serves as a portal to all modding-related pages on the wiki.
 +
 
 +
; Using Mods:
 +
* [[Mod#Installing Mods|Installing mods]]
 +
* [[Mod#Enabling Mods|Enabling mods in-game]]
 +
 
 +
; Guides and references:
 +
* [[Modding guide|Modding Guide]]
 +
* [[Modding pitfalls]] for troubleshooting
 +
 
 +
* [[Mod#Mod Format|Mod Format]] and [[Game folders and files]]
 +
* [[Mod#Publish on Steam Workshop|Publish on Steam Workshop]]
 +
* [[Memory hacking]], [[Main:Offset Finding Methods|Offset Finding Methods]]
 +
* [[Character table]]
 +
 
 +
; Where to get help?
 +
* This [http://www.bay12forums.com/smf/index.php?board=13.0 forum] is the official DF subforum dedicated to discussions about modding.
 +
* [https://discord.com/channels/329272032778780672/629902895138996264 Kitfox modding discord]
 +
* [https://docs.dfhack.org/en/stable/docs/Introduction.html#getting-help DFhack questions]
 +
 
 +
; Modding tools
 +
There are several [[Utilities#Modding_tools|utilities]] that assist in modding efforts. There is [http://www.bay12forums.com/smf/index.php?topic=28829.0 a list of them] on the [[Bay 12 Forums]].
 +
* Text Editors are used in all areas of modding. Use a good text editor to edit files and search into multiple files (like the free [https://notepad-plus-plus.org/ Notepad++] for example) or more advanced editors capable of highlighting and formatting the displayed text (like [[Utilities#DF_RAW_Language_server|DF RAW Language server]])
 +
* Image Editor will be needed for doing custom graphics. [https://www.getpaint.net/ Paint.NET], Photoshop and GIMP are the most used, but whatever supports the .png format will work.
 +
 
 +
=== Documentation===
 +
; [[Raw file]]s
  
−
{{split}}
+
These object files, stored in <code>/data/vanilla/*/objects/</code>, define various specifics of game items, materials, and creatures, and can be changed using mods to alter how the game behaves. These are text based and can be edited with any text editor, however, editing the vanilla raw files is now discouraged.
  
−
{{For/see|a list of Dwarf Fortress mods|[[List of mods]]}}
+
See [[Token|Token reference]] - It's always good to refer to tokens on the wiki. Even experienced modders have to look up tokens! A list of articles about tokens can be found here.
  
−
'''Modding''' refers to modifying the game's files. ''Dwarf Fortress'' is remarkably moddable.
+
; [[Graphics|Graphics Files]]:
  
−
== Resource Overview==
+
The `/data/art/` subfolder of Dwarf Fortress is used to store user-customizable graphics sets.
−
This section serves as a portal to all modding-related pages on the wiki.  
 
  
−
Game data documentation:
+
; [[Reaction]]s:
−
* [[Token]]s
 
−
* [[Raw file]]
 
−
* [[Reactions]]
 
−
* [[syndrome]]
 
  
−
Tools & Utilities
+
; [[Language token|Language]] and [[Speech file]]:
−
* [http://www.bay12forums.com/smf/index.php?board=13.0 Official bay12 Forum for modding]
 
−
* [[Utilities#Modding tools]]
 
−
* [[Character table]]
 
  
−
Guides:
+
; [[Audio|Sound and Music files]]:
−
* [[#Guide|Guide to Modding]]
 
−
* [[Memory hacking]], [[Main:Offset Finding Methods|Offset Finding Methods]]
 
−
* [[Category:DF2014:Modding Examples]]
 
  
−
Game Files:
+
All sound and music files used by ''Dwarf Fortress'' are stored in the [https://en.wikipedia.org/wiki/Ogg .ogg] format within the <code>/data/sound/</code> subfolders. You can replace the existing ogg files with different ones. That has to be performed manually and isn't actually supported by the game. You can also change some of the definitions of when certain musical cues are played, using available [[music token]]s and [[sound token]]s in the raw files. However, you can't add new music or sounds other than replacing what's already there.
−
* Gameplay settings: [[announcements.txt]] • [[d_init.txt]]
 
−
* Settings: [[colors.txt]] • [[init.txt]] • [[interface.txt]]
 
−
* Log files: [[errorlog.txt]] • [[gamelog.txt]]
 
−
* [[Saved game folder]] <!-- with steam the savegame, setting and mod folders will detach from the game folder [[Mod Structure]]-->
 
  
−
Miscellaneous
+
=== Best practice ===
−
* Development: [[DF2014:Release information|Release information]] • [[Main:Dwarf_Fortress_Talk|Developer diaries]] • [[Main:Dwarf_Fortress_Development|Roadmap]]
+
The current best practice is to not modify the original raw files, since most modifications can be made via mods. Mods can add new objects, add tokens to existing objects, and cut objects entirely. You should prefer SELECT over CUT, and prefer CUT over not loading vanilla raws.
−
* [[Main:Screenshot|Screenshot]]
 
  
 
== Guide ==
 
== Guide ==
Line 46: Line 62:
  
 
=== Token reference ===
 
=== Token reference ===
−
 
 
It's always good to refer to tokens on the wiki. Even experienced modders have to look up tokens! A list of articles about tokens can be found [[Token|here]].
 
It's always good to refer to tokens on the wiki. Even experienced modders have to look up tokens! A list of articles about tokens can be found [[Token|here]].
  
 
=== Basics of DF modding ===
 
=== Basics of DF modding ===
 +
To make a mod, one must put a folder into the <code>/mods/</code> folder. The vast majority of modifications to the game can be done via this method. This folder should contain a file named "info.txt" and two subfolders: "graphics" (where you insert [[Graphics set repository|graphics sets]]), and "objects", which contains all the data for, generally, everything in the game that is not hardcoded.
  
−
All the base data that can be edited by prospective modders can be found in the \raw\ folder. This folder contains two subfolders: "graphics" (where you insert [[Graphics set repository|graphics sets]]), and "objects", which contains all the data for, generally, everything in the game that is not hardcoded.
+
The [[info.txt]] is formatted like so:
  
−
Within the \raw\objects folder are a large number of text files - these are the [[raw file|raw files]], and editing them is quite easy - you can also create your own if you wish. For now, take a look at one of the existing files. For example, if you open creature_standard.txt, it should look something like this:
+
{{code|
 +
[ID:my_first_mod]
 +
[NUMERIC_VERSION:1]
 +
[DISPLAYED_VERSION:1.0.0]
 +
[EARLIEST_COMPATIBLE_NUMERIC_VERSION:1]
 +
[EARLIEST_COMPATIBLE_DISPLAYED_VERSION:1.0.0]
 +
[AUTHOR:Your Name Here]
 +
[NAME:My First Mod]
 +
[DESCRIPTION:A cool mod I made!]
 +
}}
  
 +
A mod should have all of these. There are a [[mod info token|few more tokens]], but the above are the important ones.
 +
 +
Most of the game's vanilla content is in the same format as mods. Many text files can be found in the subfolders of the <code>/data/vanilla</code> folder - these are the [[raw file|raw files]], and using them as a basis for modification is quite easy. For now, we will take a look at one of the existing files. For example, if you open <code>/data/vanilla/vanilla_creatures/creature_standard.txt</code>, it should look something like this:
 +
 +
{{code|
 
  creature_standard
 
  creature_standard
 
   
 
   
Line 66: Line 96:
 
     [CREATURE_SOLDIER_TILE:2]
 
     [CREATURE_SOLDIER_TILE:2]
 
  ...
 
  ...
 +
}}
  
−
As you can see, each file comprises a header string stating the file name, a second header stating the type of object data it contains, followed by the contents of the file itself. These are all necessary elements of the file, and without them, the file will be ignored by the game. You may have also noticed the file naming scheme - this is also important; files containing creatures have names starting with "creature_", entity file names must begin with "entity_", etc..
+
As you can see, each file comprises a header string stating the file name, a second header stating the type of object data it contains, followed by the contents of the file itself. These are all necessary elements of the file, and without them, the file will be ignored by the game.  
 +
 
 +
'''In other words, to be recognized by the game, a raw file must have all of the following:'''
 +
 
 +
# A filename that refers to the type of objects contained therein. '''Creature files must start with creature_, entity files must start with entity_, and so on.'''
 +
# The filename on the first line of the file.
 +
# [OBJECT:type], where "type" is replaced with the relevant object type.
  
 
Below the headers, there begins a list of entries. Each entry is made up of its own header (in this case, "[CREATURE:DWARF]"), again stating the type of object, and then the object's unique identifier - if an identifier isn't unique, the game will mess up and you'll get some serious, and potentially very trippy, errors. ([[Duplicated raws|For example...]])  Below that, we have the body of the entry, which determines the entry's specific properties.
 
Below the headers, there begins a list of entries. Each entry is made up of its own header (in this case, "[CREATURE:DWARF]"), again stating the type of object, and then the object's unique identifier - if an identifier isn't unique, the game will mess up and you'll get some serious, and potentially very trippy, errors. ([[Duplicated raws|For example...]])  Below that, we have the body of the entry, which determines the entry's specific properties.
Line 75: Line 112:
 
Before we continue, a few key things to remember when modding the raw files:
 
Before we continue, a few key things to remember when modding the raw files:
  
−
* Try to avoid modifying the existing raw files when adding objects. It makes removing mods far easier.
+
* Try to avoid modifying the existing raw files when possible. You should make a mod instead!
−
* When adding files, all you need to include to ensure proper references are maintained is the token identifiers.  The game will load up all *.txt files in the raw folder, and searches through them by tokens.  For example, you can add a new pair of leather boots and not even have to add it to the item_shoes.txt file, but rather make your own file, say item_shoes_new.txt and ensure you have the token listed, ex. [ITEM_SHOES:ITEM_SHOES_BOOTS_NEW].
+
* When adding files, token identifiers are all you need to include to ensure proper references are maintained.  The game searches through all loaded raw files by tokens.  For example, you can add a new pair of leather boots and not even have to add it to a file named item_shoes.txt, but rather your own file, say item_shoes_new.txt and ensure you have the token listed, ex. [ITEM_SHOES:ITEM_SHOES_BOOTS_NEW].
  
−
* If you want to edit an already-existing creature, always back up the files you plan on editing to a different location. Since v0.31.22, the game no longer loads backup files with an extension other than ".txt", but duplicate entries are still a very bad thing.
+
* When a new world is generated, the mods included are "baked in" and cannot be modified except to be updated--for this, the game checks that the mod used by the save is of a compatible NUMERIC_VERSION.
−
* When a new world is generated, all the raw files get copied into a \raw\ folder within the applicable save folder. If you want to change something within a world that's already been generated, you'll have to edit those files, not the ones in ~DF\raw\objects.
+
* There's nothing stopping you from just copying an existing creature/entity/whatever, changing the identifier, and modifying it. This can save you a lot of time, especially when it comes to entities.
−
* There's nothing stopping you from just copying an existing creature/entity/whatever, changing the identifier, and modifying it. This can save you a lot of time, especially when it comes to entities... which are coincidentally what we'll be talking about next.
+
 
 +
=== Modifying the vanilla objects ===
 +
 
 +
You should not modify the vanilla raws where they originally are if you can help it. Instead, patch them using the patching functions provided with ''Dwarf Fortress'' since v50.01.
 +
 
 +
There are two patching functions: SELECT and CUT. When SELECT is used, it lets you make changes to an object without needing the entire entry to be present in your mod file. When CUT is used, it forces the game to not use that object, even though it is still found in the vanilla raws (or in any other mods earlier in the load order). Both of these functions take the form of tokens. These functions are not universally applicable to any token found in any entry, just the following list of objects:
 +
 
 +
CREATURE, ENTITY, INTERACTION, ITEM, WORD, TRANSLATION, SYMBOL, INORGANIC, PLANT, MUSIC, REACTION, SOUND
 +
 
 +
The syntax required for these functions is: '''['''<function>'''_'''<object>''':'''<specific object being affected>''']'''. For instance, [CUT_PLANT:MUSHROOM_HELMET_PLUMP] cuts the plump helmet object in the vanilla file plant_standard.txt, so the game will not use that object at all. However, [SELECT_ITEM_HELM:ITEM_HELM_HELM] does not select the helm object from the vanilla file item_helm.txt, even though that's how the object appears in that file, because there is no [SELECT_ITEM_HELM] token. Instead, the helm would be selected with [SELECT_ITEM:ITEM_HELM_HELM].
 +
 
 +
For example, if you wanted to mod beards onto dwarven women while also removing elephants from the game:
 +
 
 +
{{code|
 +
creature_mypatch
 +
 
 +
[OBJECT:CREATURE]
 +
 
 +
[SELECT_CREATURE:DWARF] starts editing DWARF from the end of the entry
 +
    [SELECT_CASTE:FEMALE]
 +
        [BODY_DETAIL_PLAN:FACIAL_HAIR_TISSUE_LAYERS]
 +
 
 +
[CUT_CREATURE:ELEPHANT] removes the ELEPHANT creature
 +
}}
 +
 
 +
Or, say, add your own reaction and building to dwarves:
 +
 
 +
{{code|
 +
entity_mypatch
 +
 
 +
[OBJECT:ENTITY]
 +
 
 +
[SELECT_ENTITY:MOUNTAIN]
 +
    [PERMITTED_REACTION:MY_REACTION]
 +
    [PERMITTED_BUILDING:MY_BUILDING]
 +
}}
 +
 
 +
And in any of these, one can add the token [LOG_CURRENT_ENTRY] somewhere under one of the objects of the file, which logs the full contents of the object in question to logs\current_entry.txt. This can be useful to make sure that the patch is doing what you think it is. For instance if [LOG_CURRENT_ENTRY] were added on the next line after [CREATURE:DWARF] in your mod file, then the dwarf object would be the object detailed in the log entry.
 +
 
 +
...Speaking of, let's move on to modifying and adding entities.
  
 
=== Modding civilizations (entities) ===
 
=== Modding civilizations (entities) ===
  
−
Entities - the objects that determine how civilizations work - are stored in entity_default.txt (though, like all other files, you may add more). They follow the same format as any other raw file:
+
Entities - the objects that determine how civilizations work - are stored in <code>vanilla_entities/entity_default.txt</code> (though, like all other files, you may add more). They follow the same format as any other raw file:
  
 +
{{code|
 
  entity_default
 
  entity_default
 
   
 
   
Line 95: Line 172:
 
     [BIOME_SUPPORT:BIOMETOKEN:FREQUENCY]
 
     [BIOME_SUPPORT:BIOMETOKEN:FREQUENCY]
 
     ...[OTHER TAGS]...
 
     ...[OTHER TAGS]...
 +
}}
  
 
Most of the time, it doesn't matter which order these tokens are in or where they're placed so long as they're below the "ENTITY:" identifier, but there are some important exceptions in the case of other files, especially creatures, which can contain a lot of "nested" tokens.
 
Most of the time, it doesn't matter which order these tokens are in or where they're placed so long as they're below the "ENTITY:" identifier, but there are some important exceptions in the case of other files, especially creatures, which can contain a lot of "nested" tokens.
  
−
"[CREATURE:]" links the civilization with a specific creature defined in a creature file. This is the creature that'll be making up the entity's population, and, therefore, the creature you'll be playing as in fortress or adventure mode if the entity is a playable one. For example, if you wanted to do something silly, you could switch the "CREATURE:DWARF" entry in entity_default.txt with "CREATURE:ELF" and you would be marching elves around in fortress mode, although they would still use dwarven technology and language and names and so forth. Oh, and before you get any funny ideas - it ''is'' possible to define more than one creature for a civ, but that won't work in quite the way you probably expect; later on, in the creature section, you'll learn about castes, which will provide a much more viable alternative, so try to bear with us until then.
+
"[CREATURE:]" links the civilization with a specific creature defined in a creature file. This is the creature that'll be making up the entity's population, and, therefore, the creature you'll be playing as in fortress or adventure mode if the entity is a playable one. For example, if you wanted to do something silly, you could switch the "CREATURE:DWARF" entry in entity_default.txt with "CREATURE:ELF" and you would be marching elves around in fortress mode, although they would still use dwarven technology, language and names and so forth. Oh, and before you get any funny ideas - it ''is'' possible to define more than one creature for a civ, but that won't work in quite the way you probably expect; it will pick only one of the defined creatures at random to use for the civ. Later on, in the creature section, you'll learn about castes, which will provide a much more viable alternative, so try to bear with us until then.
  
 
"[TRANSLATION:]" defines the language file that the entity will be using, which will determine what their untranslated words are for things. This doesn't determine which words they use for naming things, only the way those words are spelled. The default language files are HUMAN, DWARF, ELF, and GOBLIN.
 
"[TRANSLATION:]" defines the language file that the entity will be using, which will determine what their untranslated words are for things. This doesn't determine which words they use for naming things, only the way those words are spelled. The default language files are HUMAN, DWARF, ELF, and GOBLIN.
Line 104: Line 182:
 
"[BIOME_SUPPORT:]" defines the biomes that civs will attempt to settle in. The "FREQUENCY" value determines the likelihood of them building there, but also raises an important point: most of the values you'll be setting for things are relative to each other. If one were to type:
 
"[BIOME_SUPPORT:]" defines the biomes that civs will attempt to settle in. The "FREQUENCY" value determines the likelihood of them building there, but also raises an important point: most of the values you'll be setting for things are relative to each other. If one were to type:
  
 +
{{code|
 
  [BIOME_SUPPORT:ANY_FOREST:1]
 
  [BIOME_SUPPORT:ANY_FOREST:1]
 
  [BIOME_SUPPORT:SAVANNA:2]
 
  [BIOME_SUPPORT:SAVANNA:2]
 +
}}
  
 
This would have very much the same effect as:
 
This would have very much the same effect as:
  
 +
{{code|
 
  [BIOME_SUPPORT:ANY_FOREST:5]
 
  [BIOME_SUPPORT:ANY_FOREST:5]
 
  [BIOME_SUPPORT:SAVANNA:10]
 
  [BIOME_SUPPORT:SAVANNA:10]
 +
}}
  
 
This holds true for a lot of values throughout the files, excluding when it simply doesn't make sense, such as in materials.
 
This holds true for a lot of values throughout the files, excluding when it simply doesn't make sense, such as in materials.
Line 116: Line 198:
 
You can find many details about the rest of the civilization tokens [[entity token|here]].  
 
You can find many details about the rest of the civilization tokens [[entity token|here]].  
  
−
Besides those mentioned, some fundamental ones are the SITE_CONTROLLABLE token, which lets you control the civ in fortress mode, the OUTSIDER_CONTROLLABLE token, which allows you to play in adventure mode as an outsider, and the ALL_MAIN_POPS_CONTROLLABLE token, which allows you to play a civ native (non-outsider) in adventure mode. Other tokens that you should pay attention to are START_BIOME and the ones regarding sites, but in general, you can just run through the aforementioned list and add or remove what you want.
+
Besides those mentioned, some fundamental ones are the <code>[SITE_CONTROLLABLE]</code> token, which lets you control the civ in fortress mode, the <code>[OUTSIDER_CONTROLLABLE]</code> token, which allows you to play in adventure mode as an outsider, and the <code>[ALL_MAIN_POPS_CONTROLLABLE]</code> token, which allows you to play a civ native (non-outsider) in adventure mode. Other tokens that you should pay attention to are START_BIOME and the ones regarding sites, but in general, you can just run through the aforementioned list and add or remove what you want.
  
−
If you have more than one civ with the SITE_CONTROLLABLE token, all the available civs from those entities will appear in the group selection section on the embark screen. It may not be immediately obvious from which species each civ may be - while this can be determined from legends mode, the topmost species in the "neighbors" display in the embark screen is always the same as the currently selected species; if your group is dwarven, dwarves will be topmost, whilst (say) elves will be topmost if your chosen group is elven. By default, the game seems to choose a civ (and therefore a species if there is more than one) at random.
+
If you have more than one civ with the <code>[SITE_CONTROLLABLE]</code> token, all the available civs from those entities will appear in the group selection section on the embark screen. It may not be immediately obvious from which species each civ may be - while this can be determined from legends mode, the topmost species in the "neighbors" display in the embark screen is always the same as the currently selected species; if your group is dwarven, dwarves will be topmost, whilst (say) elves will be topmost if your chosen group is elven. By default, the game seems to choose a civ (and therefore a species if there is more than one) at random.
  
 
You can also attempt to discern the civ yourself by the names it uses - this is the realm of "symbols", collections of words centered around a specific concept. The civ will use the words comprising whatever symbols are applicable to it for various things. This association might be a little confusing at first, so, let's refer to the DWARF entity:
 
You can also attempt to discern the civ yourself by the names it uses - this is the realm of "symbols", collections of words centered around a specific concept. The civ will use the words comprising whatever symbols are applicable to it for various things. This association might be a little confusing at first, so, let's refer to the DWARF entity:
  
 +
{{code|
 
  [SELECT_SYMBOL:WAR:NAME_WAR]
 
  [SELECT_SYMBOL:WAR:NAME_WAR]
 
  [SUBSELECT_SYMBOL:WAR:VIOLENT]
 
  [SUBSELECT_SYMBOL:WAR:VIOLENT]
Line 128: Line 211:
 
  [SELECT_SYMBOL:SIEGE:NAME_SIEGE]
 
  [SELECT_SYMBOL:SIEGE:NAME_SIEGE]
 
  [SUBSELECT_SYMBOL:SIEGE:VIOLENT]
 
  [SUBSELECT_SYMBOL:SIEGE:VIOLENT]
 +
}}
  
 
Here, we can see that dwarves will generally name their wars first after words in the "NAME_WAR" symbol group, and then, after words in the "VIOLENT" symbol group. This might, for example, result in a war being named "The War of Carnage". The symbols used for the other types of conflict are arrayed in a similar fashion. It would be trivial to replace the instances of VIOLENT with, say, PEACE and end up with a battle called "The Clash of Calm" or something.
 
Here, we can see that dwarves will generally name their wars first after words in the "NAME_WAR" symbol group, and then, after words in the "VIOLENT" symbol group. This might, for example, result in a war being named "The War of Carnage". The symbols used for the other types of conflict are arrayed in a similar fashion. It would be trivial to replace the instances of VIOLENT with, say, PEACE and end up with a battle called "The Clash of Calm" or something.
  
 +
{{code|
 
  [SELECT_SYMBOL:ROAD:NAME_ROAD]
 
  [SELECT_SYMBOL:ROAD:NAME_ROAD]
 
  [SELECT_SYMBOL:TUNNEL:NAME_TUNNEL]
 
  [SELECT_SYMBOL:TUNNEL:NAME_TUNNEL]
 
  [SELECT_SYMBOL:BRIDGE:NAME_BRIDGE]
 
  [SELECT_SYMBOL:BRIDGE:NAME_BRIDGE]
 
  [SELECT_SYMBOL:WALL:NAME_WALL]
 
  [SELECT_SYMBOL:WALL:NAME_WALL]
 +
}}
  
 
The above applies here. Dwarves are fond of naming their roads and tunnels after... roads and tunnels.
 
The above applies here. Dwarves are fond of naming their roads and tunnels after... roads and tunnels.
  
 +
{{code|
 
  [SELECT_SYMBOL:REMAINING:ARTIFICE]
 
  [SELECT_SYMBOL:REMAINING:ARTIFICE]
 
  [SELECT_SYMBOL:REMAINING:EARTH]
 
  [SELECT_SYMBOL:REMAINING:EARTH]
Line 148: Line 235:
 
  [CULL_SYMBOL:ALL:UGLY]
 
  [CULL_SYMBOL:ALL:UGLY]
 
  [CULL_SYMBOL:ALL:NEGATOR]
 
  [CULL_SYMBOL:ALL:NEGATOR]
 +
}}
  
 
This section deals with everything else. The things that haven't already been dealt with (hence the "REMAINING") - such as site names, kingdom names, the names of individuals, and such - will have names from the ARTIFICE and EARTH symbol groups. After that, the dwarf entity is told to cull all inappropriate symbols - this applies to everything (hence the "ALL") so if the game happens to choose a symbol associated with, say, EVIL for one of the battles, it'll scrap that name and try again. This sort of thing adds a lot of flavour to DF's entities and can account for a lot of a civ's perceived personality.
 
This section deals with everything else. The things that haven't already been dealt with (hence the "REMAINING") - such as site names, kingdom names, the names of individuals, and such - will have names from the ARTIFICE and EARTH symbol groups. After that, the dwarf entity is told to cull all inappropriate symbols - this applies to everything (hence the "ALL") so if the game happens to choose a symbol associated with, say, EVIL for one of the battles, it'll scrap that name and try again. This sort of thing adds a lot of flavour to DF's entities and can account for a lot of a civ's perceived personality.
Line 155: Line 243:
 
An easy method of creating a civilization is just to copy-paste a similar one to the bottom of the entity_default.txt file and edit things to your liking. Remember to always change the civ's "ENTITY:" identifier! This can be anything, so long as it's not already existing.
 
An easy method of creating a civilization is just to copy-paste a similar one to the bottom of the entity_default.txt file and edit things to your liking. Remember to always change the civ's "ENTITY:" identifier! This can be anything, so long as it's not already existing.
  
−
At the end of some of the default entries you'll find a list of positions, both ones that'll directly affect you in fort mode (such as nobles) and ones that'll primarily affect worldgen and adventure mode. A list of the tokens applicable to positions can be found [[position token|here]]; they don't require a great deal of explanation.
+
At the end of some of the default entries you'll find a list of positions, both ones that'll directly affect you in fort mode (such as nobles) and ones that'll primarily affect worldgen and adventure mode. A list of the tokens applicable to positions can be found [[position token|here]]; they don't require a great deal of explanation, but that can be found in [[Advanced Entity Position Mechanics]]
  
 
==== Trade ====
 
==== Trade ====
Line 162: Line 250:
 
* [[Entity token#ACTIVE_SEASON|[ACTIVE_SEASON]]] - Defines the seasons when an entity may visit your fortress.
 
* [[Entity token#ACTIVE_SEASON|[ACTIVE_SEASON]]] - Defines the seasons when an entity may visit your fortress.
 
* [[Entity token#PROGRESS_TRIGGER_POPULATION|[PROGRESS_TRIGGER_*]]] - Defines the triggers which control when an entity will become interested in your fortress.
 
* [[Entity token#PROGRESS_TRIGGER_POPULATION|[PROGRESS_TRIGGER_*]]] - Defines the triggers which control when an entity will become interested in your fortress.
−
* [[Entity token#COMMON_DOMESTIC_PACK|[COMMON_DOMESTIC_PACK]]] - Allows the civilization to use domestic pack animals. If an entity lacks pack animals (pr ability to pull wagons), it will be unable to send caravans (showing as {{DFtext|No Trade|6:1}} at the [[embark]] screen), unless it has domesticated any suitable animal species.
+
* [[Entity token#COMMON_DOMESTIC_PACK|[COMMON_DOMESTIC_PACK]]] - Allows the civilization to use domestic pack animals. If an entity lacks pack animals (or ability to pull wagons), it will be unable to send caravans (showing as {{DFtext|No Trade|6:1}} at the [[embark]] screen), unless it has domesticated any suitable animal species or is forced to use a non-suitable creature by the [ANIMAL] definition [ALWAYS_WAGON_PULLER] on creature, caste or class.
 
* [[Entity token#COMMON_DOMESTIC_PULL|[COMMON_DOMESTIC_PULL]]] - Allows the civilization to use domestic animals to pull [[wagon]]s, assuming their [[Ethic#KILL_PLANT|KILL_PLANT ethic]] permits them to use wagons in the first place.
 
* [[Entity token#COMMON_DOMESTIC_PULL|[COMMON_DOMESTIC_PULL]]] - Allows the civilization to use domestic animals to pull [[wagon]]s, assuming their [[Ethic#KILL_PLANT|KILL_PLANT ethic]] permits them to use wagons in the first place.
 
* [[Entity token#MERCHANT_BODYGUARDS|[MERCHANT_BODYGUARDS]]] - Caravan will be guarded by [[soldier]]s.
 
* [[Entity token#MERCHANT_BODYGUARDS|[MERCHANT_BODYGUARDS]]] - Caravan will be guarded by [[soldier]]s.
Line 176: Line 264:
 
In the most basic sense, a creature is a series of body parts. These parts are defined in their own file, and we'll talk about them later, as a specific aspect of how creatures work, which throws off a lot of prospective modders, is the relationship between body parts, tissues, and materials. We're going to show you part of the creature entry for a bronze colossus (bear with us):
 
In the most basic sense, a creature is a series of body parts. These parts are defined in their own file, and we'll talk about them later, as a specific aspect of how creatures work, which throws off a lot of prospective modders, is the relationship between body parts, tissues, and materials. We're going to show you part of the creature entry for a bronze colossus (bear with us):
  
 +
{{code|
 
  ...
 
  ...
 
  [BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
 
  [BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
Line 190: Line 279:
 
  [TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
 
  [TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
 
  ...
 
  ...
 +
}}
  
 
At the top, we can see the "BODY:" token, followed by a list of body parts. As you've probably guessed, these parts make up the physical form of the colossus. But the colossus has to be made out of something - it has to have tissues, and those tissues also have to be made out of something - in this case, bronze.
 
At the top, we can see the "BODY:" token, followed by a list of body parts. As you've probably guessed, these parts make up the physical form of the colossus. But the colossus has to be made out of something - it has to have tissues, and those tissues also have to be made out of something - in this case, bronze.
Line 201: Line 291:
 
Firstly, there are material and tissue templates. Let's say you were going to make a lot of creatures out of bronze, and you didn't want to have to copy and paste the bronze tissue all over the place. Instead, you create a tissue template. This goes, as you've probably guessed, in a tissue template file.
 
Firstly, there are material and tissue templates. Let's say you were going to make a lot of creatures out of bronze, and you didn't want to have to copy and paste the bronze tissue all over the place. Instead, you create a tissue template. This goes, as you've probably guessed, in a tissue template file.
  
 +
{{code|
 
  [TISSUE_TEMPLATE:BRONZE_TEMPLATE]
 
  [TISSUE_TEMPLATE:BRONZE_TEMPLATE]
 
     [TISSUE_NAME:bronze:bronze]
 
     [TISSUE_NAME:bronze:bronze]
Line 210: Line 301:
 
     [CONNECTS]
 
     [CONNECTS]
 
     [TISSUE_SHAPE:LAYER]
 
     [TISSUE_SHAPE:LAYER]
 +
}}
  
 
Now, instead of applying the tissue to each and every bronze creature you're making, you can just refer to the template:
 
Now, instead of applying the tissue to each and every bronze creature you're making, you can just refer to the template:
  
 +
{{code|
 
  ...
 
  ...
 
  [BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
 
  [BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
Line 219: Line 312:
 
  [TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
 
  [TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
 
  ...
 
  ...
 +
}}
  
 
Material templates work in the same way, but refer to materials instead of tissues.
 
Material templates work in the same way, but refer to materials instead of tissues.
Line 224: Line 318:
 
However, if we're looking at something like a dwarf, even with the templates, editing can get very slow indeed:
 
However, if we're looking at something like a dwarf, even with the templates, editing can get very slow indeed:
  
 +
{{code|
 
     ...
 
     ...
 
     [USE_MATERIAL_TEMPLATE:SKIN:SKIN_TEMPLATE]
 
     [USE_MATERIAL_TEMPLATE:SKIN:SKIN_TEMPLATE]
Line 247: Line 342:
 
     [USE_TISSUE_TEMPLATE:MUSCLE:MUSCLE_TEMPLATE]
 
     [USE_TISSUE_TEMPLATE:MUSCLE:MUSCLE_TEMPLATE]
 
     ...
 
     ...
 +
}}
  
 
This is where body detail plans, which have their own file, and are designed to help automate some of the more common processes in creature creation, come in. The first entry in b_detail_plan_default.txt does exactly what we've been trying to do above: it takes all the common materials and shoves them into one plan, which can be referenced with a single token.
 
This is where body detail plans, which have their own file, and are designed to help automate some of the more common processes in creature creation, come in. The first entry in b_detail_plan_default.txt does exactly what we've been trying to do above: it takes all the common materials and shoves them into one plan, which can be referenced with a single token.
  
 +
{{code|
 
     ...
 
     ...
 
     [BODY_DETAIL_PLAN:STANDARD_MATERIALS]
 
     [BODY_DETAIL_PLAN:STANDARD_MATERIALS]
 
     ...
 
     ...
 +
}}
  
 
Much easier. But what about the TISSUE_LAYER tokens? Will we have to type out all of those manually?
 
Much easier. But what about the TISSUE_LAYER tokens? Will we have to type out all of those manually?
Line 258: Line 356:
 
Nope, detail plans have that covered as well. It's possible to place variable arguments into a detail plan. For example:
 
Nope, detail plans have that covered as well. It's possible to place variable arguments into a detail plan. For example:
  
 +
{{code|
 
  [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS]
 
  [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS]
 
     [BP_LAYERS:BY_CATEGORY:BODY:ARG3:50:ARG2:5:ARG1:1]
 
     [BP_LAYERS:BY_CATEGORY:BODY:ARG3:50:ARG2:5:ARG1:1]
Line 267: Line 366:
 
     [BP_LAYERS:BY_CATEGORY:NOSE:ARG5:4:ARG1:1]
 
     [BP_LAYERS:BY_CATEGORY:NOSE:ARG5:4:ARG1:1]
 
     ...
 
     ...
 +
}}
  
 
First an argument is placed in the plan (ARG1, ARG2 etc.), followed by the thickness of the tissue that will be inserted in place of the argument. So when we reference the VERTEBRATE_TISSUE_LAYERS plan, we'll be able to do something like this:
 
First an argument is placed in the plan (ARG1, ARG2 etc.), followed by the thickness of the tissue that will be inserted in place of the argument. So when we reference the VERTEBRATE_TISSUE_LAYERS plan, we'll be able to do something like this:
  
 +
{{code|
 
     [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 
     [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 +
}}
  
 
ARG1 in the detail plan is replaced by SKIN, the first tissue we entered. ARG2 is replaced by FAT, ARG3 by MUSCLE, ARG4 by BONE, and ARG5 by CARTILAGE. Hence, our creature's body part designated as BODY is made up of SKIN with thickness 1, FAT with thickness 5, and MUSCLE with thickness 50. Its nose is made up of SKIN (thickness 1) and CARTILAGE (thickness 4).
 
ARG1 in the detail plan is replaced by SKIN, the first tissue we entered. ARG2 is replaced by FAT, ARG3 by MUSCLE, ARG4 by BONE, and ARG5 by CARTILAGE. Hence, our creature's body part designated as BODY is made up of SKIN with thickness 1, FAT with thickness 5, and MUSCLE with thickness 50. Its nose is made up of SKIN (thickness 1) and CARTILAGE (thickness 4).
Line 276: Line 378:
 
Things left out of the body plans aside, our dwarf's entire body, material, tissue and tissue layer tokens have been boiled down to this:
 
Things left out of the body plans aside, our dwarf's entire body, material, tissue and tissue layer tokens have been boiled down to this:
  
 +
{{code|
 
     ...
 
     ...
 
     [BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
 
     [BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
Line 283: Line 386:
 
     [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 
     [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 
     ...
 
     ...
 +
}}
  
 
This can save you a lot of time and space if you're making lots of changes common to many creatures. In general, if you're making a creature that's fleshy or chitinous, there are detail plans already included in the game to help you out. You should only have to resort to declaring tissues individually (like our bronze colossus) if you're doing something really out-of-the-ordinary.
 
This can save you a lot of time and space if you're making lots of changes common to many creatures. In general, if you're making a creature that's fleshy or chitinous, there are detail plans already included in the game to help you out. You should only have to resort to declaring tissues individually (like our bronze colossus) if you're doing something really out-of-the-ordinary.
  
−
Another great thing about templates (and so, detail plans) is that they can be modified after being declared. Let's say we wanted our dwarves to be perpetually on fire (don't ask). We declare the body stuff normally:
+
Another great thing about templates (and so, detail plans) is that they can be modified after being declared. Let's say we wanted our dwarves to be perpetually on fire (don't ask). We leave the body stuff declared normally:
  
 +
{{code|
 
     ...
 
     ...
 
     [BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
 
     [BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
Line 295: Line 400:
 
     [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 
     [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 
     ...
 
     ...
 +
}}
  
−
We then select the appropriate material:
+
We then, in our own mod, select the appropriate material:
  
−
    ...
+
{{code|
−
    [BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
+
[SELECT_CREATURE:DWARF]
−
    THROAT:NECK:SPINE:BRAIN:SKULL:5FINGERS:5TOES:MOUTH:FACIAL_FEATURES:TEETH:RIBCAGE]
 
−
    [BODY_DETAIL_PLAN:STANDARD_MATERIALS]
 
−
    [BODY_DETAIL_PLAN:STANDARD_TISSUES]
 
−
    [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 
 
     [SELECT_MATERIAL:SKIN]
 
     [SELECT_MATERIAL:SKIN]
 
         [MAT_FIXED_TEMP:10600]
 
         [MAT_FIXED_TEMP:10600]
 
     ...
 
     ...
 +
}}
  
 
We don't want them burning to death, so we'll need to stop that from happening:
 
We don't want them burning to death, so we'll need to stop that from happening:
  
−
    ...
+
{{code|
−
    [BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
+
[SELECT_CREATURE:DWARF]
−
    THROAT:NECK:SPINE:BRAIN:SKULL:5FINGERS:5TOES:MOUTH:FACIAL_FEATURES:TEETH:RIBCAGE]
 
−
    [BODY_DETAIL_PLAN:STANDARD_MATERIALS]
 
−
    [BODY_DETAIL_PLAN:STANDARD_TISSUES]
 
−
    [BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
 
 
     [SELECT_MATERIAL:SKIN]
 
     [SELECT_MATERIAL:SKIN]
 
         [MAT_FIXED_TEMP:10600]
 
         [MAT_FIXED_TEMP:10600]
Line 321: Line 420:
 
         [HEATDAM_POINT:NONE]
 
         [HEATDAM_POINT:NONE]
 
     ...
 
     ...
 +
}}
  
 
Note that this makes use of DF's built-in temperature scale. You can read more about that [[Temperature|on this page]]. We're also referencing material tokens, which we haven't gone over yet - we'll talk about making your own materials later.
 
Note that this makes use of DF's built-in temperature scale. You can read more about that [[Temperature|on this page]]. We're also referencing material tokens, which we haven't gone over yet - we'll talk about making your own materials later.
Line 330: Line 430:
 
To understand the true potential of the caste system, we only need to take a look at the raws for antmen, found in creature_subterrenean.txt:
 
To understand the true potential of the caste system, we only need to take a look at the raws for antmen, found in creature_subterrenean.txt:
  
 +
{{code|
 
     ...
 
     ...
 
     [CASTE:WORKER]
 
     [CASTE:WORKER]
Line 365: Line 466:
 
             [ATTACK_VERB:punch:punches]
 
             [ATTACK_VERB:punch:punches]
 
     ...
 
     ...
 +
}}
  
 
It's evident that the process of creating and editing castes is comparable to the modifications we were making to tissues and materials earlier: A caste is declared, and modifications to the base creature are made. Declared castes can be selected and subsequently modified, again, just like tissues and materials.
 
It's evident that the process of creating and editing castes is comparable to the modifications we were making to tissues and materials earlier: A caste is declared, and modifications to the base creature are made. Declared castes can be selected and subsequently modified, again, just like tissues and materials.
  
−
In this case, each caste is declared, given its own name, and a POP_RATIO, which determines how commonly a birth results in that caste - for every 10000 workers born, there'll be an average of 1000 soldiers, 5 drones and one queen. You've probably also noticed that the DRONE and QUEEN castes have the MALE and FEMALE tokens respectively - these tokens determine how breeding works. A creature without both a MALE caste and a FEMALE caste will be unable to breed (no