Dwarf Fortress Wiki - User contributions [en]

Modding

2018-04-28T21:43:37Z

Zilpin: /* Utilities */

{{Quality|Exceptional|14:13, 7 November 2013 (UTC)}}
{{av}}
{{catbox|DF2014:Modding}}

{{For/see|a list of Dwarf Fortress mods|[[List of mods]]}}

'''Modding''' refers to modifying the game's files. ''Dwarf Fortress'' is remarkably moddable.

== Guide ==
This is intended to be a guide to inform those new to ''Dwarf Fortress'' modding on what elements of the game can be modified, and how. After reading through this guide, a user should be capable of editing creatures, entities, materials ''et al'', and creating their own.

Generally, breaking stuff is fine - nothing that can be changed will affect the DF executable, and new additions can be easily removed.

This guide is based on [[40d:Modding guide|Teldin's guide]], originally created for version 0.27.176.39c. Per wiki tradition, it has been updated through all the major releases since then; hopefully it reflects current knowledge.

=== 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 [http://dwarffortresswiki.org/index.php/Token here].

=== Basics of DF modding ===

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.

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:

creature_standard

[OBJECT:CREATURE]

[CREATURE:DWARF]
[DESCRIPTION:A short, sturdy creature fond of drink and industry.]
[NAME:dwarf:dwarves:dwarven]
[CASTE_NAME:dwarf:dwarves:dwarven]
[CREATURE_TILE:1][COLOR:3:0:0]
[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..

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. Below that, we have the body of the entry, which determines the entry's specific properties.

The body of an entry is made up of a series of "tokens", which are essentially flags that can be added or removed to affect the entry's attributes. Most of these effects are hardcoded: for example, it's possible to make a creature only eat meat with the [CARNIVOROUS] token, but it's impossible to create your own token detailing a specific diet for the creature.

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.
* 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].

* 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, 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... which are coincidentally what we'll be talking about next.

=== 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:

entity_default

[OBJECT:ENTITY]

[ENTITY:ENTITYNAME]
[CREATURE:CREATURETYPE]
[TRANSLATION:LANGUAGETYPE]
[BIOME_SUPPORT:BIOMETOKEN:FREQENCY]
...[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.

"[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 will therefore be 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.

"[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.

"[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:ANY_FOREST:1]
[BIOME_SUPPORT:SAVANNA:2]

This would have very much the same effect as:

[BIOME_SUPPORT:ANY_FOREST:5]
[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.

You can find many details about the rest of the civilization tokens [[entity token|here]]. Besides those mentioned, some fundamental ones are the CIV_CONTROLLABLE token, which lets you control the civ in fortress mode, the INDIV_CONTROLLABLE token, which allows you to play the civ in adventure mode as an outsider, and the ADVENTURE_TIER 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 CIV_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.

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 obfuscating at first, so I'll run through it. Let's refer to the DWARF entity:

[SELECT_SYMBOL:WAR:NAME_WAR]
[SUBSELECT_SYMBOL:WAR:VIOLENT]
[SELECT_SYMBOL:BATTLE:NAME_BATTLE]
[SUBSELECT_SYMBOL:BATTLE:VIOLENT]
[SELECT_SYMBOL:SIEGE:NAME_SIEGE]
[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.

[SELECT_SYMBOL:ROAD:NAME_ROAD]
[SELECT_SYMBOL:TUNNEL:NAME_TUNNEL]
[SELECT_SYMBOL:BRIDGE:NAME_BRIDGE]
[SELECT_SYMBOL:WALL:NAME_WALL]

The above applies here. Dwarves are fond of naming their roads and tunnels after roads and tunnels.

[SELECT_SYMBOL:REMAINING:ARTIFICE]
[SELECT_SYMBOL:REMAINING:EARTH]
[CULL_SYMBOL:ALL:DOMESTIC]
[CULL_SYMBOL:ALL:SUBORDINATE]
[CULL_SYMBOL:ALL:EVIL]
[CULL_SYMBOL:ALL:UNTOWARD]
[CULL_SYMBOL:ALL:FLOWERY]
[CULL_SYMBOL:ALL:NEGATIVE]
[CULL_SYMBOL:ALL:UGLY]
[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 innapropriate 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.

Another basic thing to note: any entity token that's dealing with weapons, armor, clothing, etc., will state the items that the civ can build natively, not necessarily the ones they can wear or use. For example, you could create a species with no clothes specified, but then rob a clothes shop in adventurer mode and wear everything you want, or give them weapons that are too large to wield and they could sell them, but not use them.

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.

=== Modding the creatures ===

Creature modding is great fun. You can change nearly any aspect of a creature or make your own completely from scratch.

Modding creatures is very similar to modding civs: it's just a matter of editing, adding, or removing tokens, enclosed in square brackets underneath the creature's [CREATURE:] header. The creature entries contain all of the information about each and every non-random creature in the game, from animals to dwarves to goblins to even caravan wagons. A lot of the creature tokens are fairly self-explanatory; you can find a list of such tokens [[creature token|here]]. But before you start creating your own creatures, you'll want to learn how the tissues system works.

==== Creature materials and tissues ====

In the most basic sense, a creature is a series of bodyparts. 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 bodyparts, tissues, and materials. We're going to show you part of the creature entry for a bronze colossus (bear with us):

...
[BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
[NO_THOUGHT_CENTER_FOR_MOVEMENT]
[TISSUE:BRONZE]
[TISSUE_NAME:bronze:bronze]
[TISSUE_MATERIAL:INORGANIC:BRONZE]
[MUSCULAR]
[FUNCTIONAL]
[STRUCTURAL]
[RELATIVE_THICKNESS:1]
[CONNECTS]
[TISSUE_SHAPE:LAYER]
[TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
...

At the top, we can see the "BODY:" token, followed by a list of bodyparts. 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.

Below the BODY token you'll see a TISSUE token, followed by an identifier, much like the others we've seen. The TISSUE block is determining how the tissue works, and which purposes it'll serve. As the colossus is just going to be made out of this one tissue, this tissue needs to act like bone, muscle, and everything else combined, hence the MUSCULAR, FUNCTIONAL and STRUCTURAL tokens. The tissue also references a material - INORGANIC:BRONZE - the properties of which are declared in the inorganic materials file, and the tissue is subsequently made out of this material. With us so far?

Below the tissue definition is the TISSUE_LAYER line. TISSUE_LAYER allows you to control where each tissue is applied. Its first argument defines if it's to search by bodypart category (BY_CATEGORY), bodypart type (BY_TYPE), or look for a specific part (BY_TOKEN). That's followed by the parts argument itself, which is in this case ALL (so the game's looking for parts in all categories, which is to say, every bodypart). This is followed by the tissue to be applied, BRONZE. So the TISSUE_LAYER token is telling the game to select all bodyparts in every category and make them out of the tissue "BRONZE". The colossus is now made of bronze.

By now you're probably thinking "Wow, if this was for a creature made out of however many tissues, this would be amazingly longwinded". And you're right. Luckily, there are two methods by which we can speed things up a lot.

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.

[TISSUE_TEMPLATE:BRONZE_TEMPLATE]
[TISSUE_NAME:bronze:bronze]
[TISSUE_MATERIAL:INORGANIC:BRONZE]
[MUSCULAR]
[FUNCTIONAL]
[STRUCTURAL]
[RELATIVE_THICKNESS:1]
[CONNECTS]
[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:

...
[BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
[NO_THOUGHT_CENTER_FOR_MOVEMENT]
[USE_TISSUE_TEMPLATE:BRONZE:BRONZE_TEMPLATE]
[TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
...

Material templates work in the same way, but refer to materials instead of tissues.

However, if we're looking at something like a dwarf, even with the templates, editing can get very slow indeed:

...
[USE_MATERIAL_TEMPLATE:SKIN:SKIN_TEMPLATE]
[USE_MATERIAL_TEMPLATE:FAT:FAT_TEMPLATE]
[USE_MATERIAL_TEMPLATE:MUSCLE:MUSCLE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:BONE:BONE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:CARTILAGE:CARTILAGE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:HAIR:HAIR_TEMPLATE]
[USE_MATERIAL_TEMPLATE:TOOTH:TOOTH_TEMPLATE]
[USE_MATERIAL_TEMPLATE:EYE:EYE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:NERVE:NERVE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:BRAIN:BRAIN_TEMPLATE]
[USE_MATERIAL_TEMPLATE:LUNG:LUNG_TEMPLATE]
[USE_MATERIAL_TEMPLATE:HEART:HEART_TEMPLATE]
[USE_MATERIAL_TEMPLATE:LIVER:LIVER_TEMPLATE]
[USE_MATERIAL_TEMPLATE:GUT:GUT_TEMPLATE]
[USE_MATERIAL_TEMPLATE:STOMACH:STOMACH_TEMPLATE]
[USE_MATERIAL_TEMPLATE:PANCREAS:PANCREAS_TEMPLATE]
[USE_MATERIAL_TEMPLATE:SPLEEN:SPLEEN_TEMPLATE]
[USE_MATERIAL_TEMPLATE:KIDNEY:KIDNEY_TEMPLATE]
[USE_TISSUE_TEMPLATE:SKIN:SKIN_TEMPLATE]
[USE_TISSUE_TEMPLATE:FAT:FAT_TEMPLATE]
[USE_TISSUE_TEMPLATE:MUSCLE:MUSCLE_TEMPLATE]
...

This is where body detail plans come in. Detail plans, of course, have their own file, and they are designed to help automate some of the more common processes in creature creation. 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.

...
[BODY_DETAIL_PLAN:STANDARD_MATERIALS]
...

Much easier. But what about the TISSUE_LAYER tokens? Will we have to type out all of those manually?

Nope, detail plans have that covered as well. It's possible to place variable arguments into a detail plan. For example:

[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS]
[BP_LAYERS:BY_CATEGORY:BODY:ARG3:50:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:BODY_UPPER:ARG3:50:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:BODY_LOWER:ARG3:50:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:ARM:ARG4:25:ARG3:25:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:ARM_UPPER:ARG4:25:ARG3:25:ARG2:5: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:

[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 bodypart 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).

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:

...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
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]
...

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:

...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
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]
...

We then select the appropriate material:

...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
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]
[MAT_FIXED_TEMP:10600]
...

We don't want them burning to death, so we'll need to stop that from happening:

...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
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]
[MAT_FIXED_TEMP:10600]
[SELECT_MATERIAL:ALL]
[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.

==== Creature castes ====

Another potentially extremely powerful part of the creature raws is the caste system. The caste system handles both true biological castes and lesser variations, such as sexes.

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:

...
[CASTE:WORKER]
[CASTE_NAME:worker ant woman:worker ant women:worker ant woman]
Female, but non-breeding.
[POP_RATIO:10000]
[CASTE:SOLDIER]
[CASTE_NAME:soldier ant woman:soldier ant women:soldier ant woman]
Female, but non-breeding.
[POP_RATIO:1000]
[CASTE:DRONE]
[MALE]
[CASTE_NAME:drone ant man:drone ant men:drone ant man]
[POP_RATIO:5]
[CASTE:QUEEN]
[FEMALE]
[CASTE_NAME:queen ant woman:queen ant women:queen ant woman]
[POP_RATIO:1]
[SELECT_CASTE:WORKER]
[SELECT_ADDITIONAL_CASTE:SOLDIER]
[SELECT_ADDITIONAL_CASTE:QUEEN]
[BODY:HUMANOID_4ARMS:2EYES:HEART:GUTS:BRAIN:MOUTH]
[BODYGLOSS:INSECT_UPPERBODY:INSECT_LOWERBODY]
[SELECT_CASTE:DRONE]
[BODY:HUMANOID_4ARMS:2EYES:HEART:GUTS:BRAIN:MOUTH:2WINGS]
[BODYGLOSS:INSECT_UPPERBODY:INSECT_LOWERBODY]
[FLIER]
[SELECT_CASTE:ALL]
[BODY_DETAIL_PLAN:CHITIN_MATERIALS]
[BODY_DETAIL_PLAN:CHITIN_TISSUES]
[BODY_DETAIL_PLAN:EXOSKELETON_TISSUE_LAYERS:CHITIN:FAT:MUSCLE]
[BODY_DETAIL_PLAN:STANDARD_HEAD_POSITIONS]
[ATTACK:PUNCH:BODYPART:BY_TYPE:GRASP]
[ATTACK_SKILL:GRASP_STRIKE]
[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.

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 asexual creatures yet, unfortunately). As they lack FEMALE, the workers and soldiers are unable to breed with the male drones.

After this, there are some modifications to bodyparts. In this case, the drones have wings and the FLIER token, which the other castes lack. It's entirely possible for creatures of different castes to have completely different body structures, even to the extent that they don't resemble each other at all. If you read the section of this guide that dealt with entities, you may remember a passing mention of multi-creature civilisations and how they don't quite work as you may think they would. The castes system is your workaround. You could create a caste that is, for all intents and purposes, a human, and another caste of the same creature that acts exactly like a giant cave spider, put the creature in a civ, and get a human-spider civ. The only flaw in this approach is that the castes will interbreed.

That's the most complex components of creature creation out of the way. You should find the rest trivial by comparison.

=== Modding items ===

Items are fairly simple to deal with. By default, each item type is contained in its own file; this may help make browsing for a specific item easier, but from a purely technical point of view, it's possible to throw all items into one file. Unfortunately, item tokens don't seem to be especially well-documented (at least not as well as the other object types), but you should be able to figure out most things by way of our explanations and your assumptions.

Let's look at the entry for, of course, the thong:

[ITEM_PANTS:ITEM_PANTS_THONG]
[NAME:thong:thongs]
[LAYER:UNDER]
[COVERAGE:25]
[LAYER_SIZE:10]
[LAYER_PERMIT:30]
[MATERIAL_SIZE:1]
[SOFT]
[LEATHER]
[STRUCTURAL_ELASTICITY_WOVEN_THREAD]

Most of these are pretty obvious if one compares them to the other entries in the file. There's a layer for the item, determining where it's worn; a coverage value to determine how well it protects you from cold and other things; a size token to determine how much it counts for when it's under something else; a layer permit token to determine how much can be worn under it; and a material size token to determine how much raw material it takes to make it.

Now, if you wanted to mod these to turn them into metal thongs (ouch!), you would simply have to add [METAL] to it somewhere. Simple! These tokens work by tying into material properties - some materials are designated as suitable for making hard items, some for soft, etc..

Weapons involve a little more detail:

[ITEM_WEAPON:ITEM_WEAPON_SWORD_2H]
[NAME:two-handed sword:two-handed swords]
[SIZE:900]
[SKILL:SWORD]
[TWO_HANDED:67500]
[MINIMUM_SIZE:62500]
[MATERIAL_SIZE:5]
[ATTACK:EDGE:100000:8000:slash:slashes:NO_SUB:1250]
[ATTACK:EDGE:50:4000:stab:stabs:NO_SUB:1000]
[ATTACK:BLUNT:100000:8000:slap:slaps:flat:1250]
[ATTACK:BLUNT:100:1000:strike:strikes:pommel:1000]

SIZE determines how heavy the weapon is. This has a substantial effect on weapon effectiveness. SKILL determines which skill is used in using the weapon; a list of skills can be found [[skill token|on this page]]. MINIMUM_SIZE determines the minimum size a creature must be before the weapon can be wielded, while TWO_HANDED determines how large a creature must be in order to wield the weapon with one hand.

Attacks take a little more explanation. The first value determines the contact area of the weapon's attack; this should be high for slashing weapons and low for bludgeoning, piercing and poking ones. The second value determines how deep the weapon penetrates - for BLUNT attacks this value is ignored as they're not supposed to penetrate anyway, but in the case of EDGE attacks it should generally be lower for slashing attacks and higher for stabbing attacks.

Following these are the nouns and verb used; they should be self-explanatory. Finally, we have the velocity modifier, which has a multiplying effect on the weapon's size for the purposes of determining how powerful it is in combat.

Other, more miscellaneous items are generally simple and shouldn't require any further explanation.

Once you've made an item, you just add it to the civ entry so a civilization can actually craft it, and it's done.

=== Modding language files ===

Let's say you added a whole new species. Sure, you could just swipe one of the existing translation files and steal their language for your species, but that's the lazy way! If you want to create a whole new language, it is very simple.

First, you'd need a whole new language_RACE file, such as language_LIZARDMAN.txt, along with "language_LIZARDMAN" at the top of the file proceeded by [OBJECT:LANGUAGE] and [TRANSLATION:LIZARDMAN]. After that, it's just a matter of copy-pasting one of the existing language lists and editing the finished 'translated' word. That's it! Then just add the translation link to your civ in entity_default.txt and it'll be added to the game on worldgen.

(Note that the name of the file doesn't actually matter; however, it's good form to name the file after a creature if only that creature speaks the language.)

=== Modding body parts ===

Imagine you have this fantastic idea for a multi-tentacled winged spider-monster. Sounds great! But in order to make this a reality you may need to create a new set of body parts for it. That's no problem! Making body parts is easy, though it may look complicated at first.

All of the default body definitions are located in body_default.txt and then linked to a creature in the creature's entry. We've talked about how bodyparts make up creatures earlier, in the creature section. You can mix and match them in the creature entry and it makes no difference, as long as they're there: each bodypart will link itself to the appropriate connection automatically when the creature is first created.

Body parts work by sections: you can add as many sections as you want to a bodypart definition, but generally you should keep it fairly low for ease of use. Each body section entry is in the, very simple, format:

[BODY:BODYNAME]
[BP:TOKENID:name][TOKENSGOHERE][DEFAULT_RELSIZE:][CATEGORY:WHATEVER]

The most important tokens are "CONTYPE" and "CON": CONTYPE means the bodypart in question is connected to a certain ''type'' of bodypart, while CON means it's connected to a ''specific'' one. TOKENID is yet another identifier, which should be unique, as it's referenced every time something uses CON or BY_TOKEN. DEFAULT_RELSIZE defines, of course, what the bodypart's size is in relation to the other parts. CATEGORY defines a category for the part, which can be unique or shared with other parts. This is referenced whenever BY_CATEGORY is used.

A list of bodypart tokens can be found [[body token|here]].

Let's take a simple example, a head:

[BODY:BASIC_HEAD]
[BP:HD:head:STP][CONTYPE:UPPERBODY][HEAD][CATEGORY:HEAD]
[DEFAULT_RELSIZE:300]

It connects directly to an upper body.

[BODY:2EYES]
[BP:REYE:right eye:STP][CONTYPE:HEAD][SIGHT][EMBEDDED][SMALL][RIGHT][CATEGORY:EYE]
[DEFAULT_RELSIZE:5]
[BP:LEYE:left eye:STP][CONTYPE:HEAD][SIGHT][EMBEDDED][SMALL][LEFT][CATEGORY:EYE]
[DEFAULT_RELSIZE:5]

These are a pair of eyes, connecting to the head.

[BODY:HUMANOID]
[BP:UB:upper body:upper bodies][UPPERBODY][CATEGORY:BODY_UPPER]
[DEFAULT_RELSIZE:1000]
[BP:LB:lower body:lower bodies][CON:UB][LOWERBODY][CATEGORY:BODY_LOWER]
[DEFAULT_RELSIZE:1000]
[BP:HD:head:STP][CON:UB][HEAD][CATEGORY:HEAD]
[DEFAULT_RELSIZE:300]
[BP:RUA:right upper arm:STP][CON:UB][LIMB][RIGHT][CATEGORY:ARM_UPPER]
[DEFAULT_RELSIZE:200]
[BP:LUA:left upper arm:STP][CON:UB][LIMB][LEFT][CATEGORY:ARM_UPPER]
[DEFAULT_RELSIZE:200]
[BP:RLA:right lower arm:STP][CON:RUA][LIMB][RIGHT][CATEGORY:ARM_LOWER]
[DEFAULT_RELSIZE:200]
[BP:LLA:left lower arm:STP][CON:LUA][LIMB][LEFT][CATEGORY:ARM_LOWER]
[DEFAULT_RELSIZE:200]
[BP:RH:right hand:STP][CON:RLA][GRASP][RIGHT][CATEGORY:HAND]
[DEFAULT_RELSIZE:80]
[BP:LH:left hand:STP][CON:LLA][GRASP][LEFT][CATEGORY:HAND]
[DEFAULT_RELSIZE:80]
[BP:RUL:right upper leg:STP][CON:LB][LIMB][RIGHT][CATEGORY:LEG_UPPER]
[DEFAULT_RELSIZE:500]
[BP:LUL:left upper leg:STP][CON:LB][LIMB][LEFT][CATEGORY:LEG_UPPER]
[DEFAULT_RELSIZE:500]
[BP:RLL:right lower leg:STP][CON:RUL][LIMB][RIGHT][CATEGORY:LEG_LOWER]
[DEFAULT_RELSIZE:400]
[BP:LLL:left lower leg:STP][CON:LUL][LIMB][LEFT][CATEGORY:LEG_LOWER]
[DEFAULT_RELSIZE:400]
[BP:RF:right foot:right feet][CON:RLL][STANCE][RIGHT][CATEGORY:FOOT]
[DEFAULT_RELSIZE:120]
[BP:LF:left foot:left feet][CON:LLL][STANCE][LEFT][CATEGORY:FOOT]
[DEFAULT_RELSIZE:120]

An entire humanoid body. The foot bone's connected to the ankle bone...

"BODYGLOSS" entries, which you can sometimes find applied to creature entries, are simply replacement words for specific part name strings in a creature. For example, you'll find the bodygloss [BODYGLOSS:CLAW_HAND:hand:claw] in body_default.txt; you can then use this in a creature via "[BODYGLOSS:CLAW_HAND]" and it'll replace all instances of "hand" with "claw" in that creature. Be warned, however—if you were to, say make a bodygloss [BODYGLOSS:EARSTALK:ear:stalk:ears:stalk], it would not only change "ear" and "ears" to "stalk" and "stalks", it would also change "h'''ear'''t" to "h'''stalk'''t"! For all intents and purposes the body part will still function as the proper part, though.

=== Modding plants ===

Plants are, again, not unlike creatures. With what you've learned so far in regard to tokens and the materials system, running through the notes included in plant_standard.txt should explain most things. [[Plant token|Here's the list of plant-specific tokens]].

Below is the [[plump helmet]] raw description:

[PLANT:MUSHROOM_HELMET_PLUMP]
[NAME:plump helmet][NAME_PLURAL:plump helmets][ADJ:plump helmet]
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[MATERIAL_VALUE:2]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
[EDIBLE_VERMIN]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PICKED_TILE:161][PICKED_COLOR:6:13:0]
[GROWDUR:300][VALUE:2]
[USE_MATERIAL_TEMPLATE:DRINK:PLANT_ALCOHOL_TEMPLATE]
[STATE_NAME_ADJ:ALL_SOLID:frozen dwarven wine]
[STATE_NAME_ADJ:LIQUID:dwarven wine]
[STATE_NAME_ADJ:GAS:boiling dwarven wine]
[MATERIAL_VALUE:2]
[DISPLAY_COLOR:5:0:0]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PREFIX:NONE]
[DRINK:LOCAL_PLANT_MAT:DRINK]

[USE_MATERIAL_TEMPLATE:SEED:SEED_TEMPLATE]
[MATERIAL_VALUE:1]
[EDIBLE_VERMIN]
[EDIBLE_COOKED]
[SEED:plump helmet spawn:plump helmet spawn:4:0:1:LOCAL_PLANT_MAT:SEED]
[SPRING][SUMMER][AUTUMN][WINTER]
[FREQUENCY:100]
[CLUSTERSIZE:5]
[PREFSTRING:rounded tops]
[WET][DRY]
[BIOME:SUBTERRANEAN_WATER]
[UNDERGROUND_DEPTH:1:3]
[SHRUB_TILE:142]
[DEAD_SHRUB_TILE:28]
[SHRUB_COLOR:5:13:0]
[DEAD_SHRUB_COLOR:5:6:0]

Let's look at this line by line:<br>
First, we define its file name. In this case it's MUSHROOM_HELMET_PLUMP. Next we define its in-game name (plump helmet) and its adjective for if you were to craft with it (e.g. plump helmet earrings).

[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[MATERIAL_VALUE:2]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]

This defines the structure and material of the plant. It references STRUCTURAL_PLANT_TEMPLATE in the first line, so if you were to say, add wings to the template, the plump helmet plant would be winged. This is for the plant itself, not the end plump helmets.

After that we get our edible tokens. These say that vermin can eat the plant, and it can be eaten raw or cooked by your dwarves. So if you wanted a plant vermin would leave alone, you'd remove the [EDIBLE_VERMIN] token.

[EDIBLE_VERMIN]
[EDIBLE_RAW]
[EDIBLE_COOKED]

Next, [PICKED_TILE:161] is the character (161 in this case) shown when the crop is harvested. See [[Main:Character table|character table]] for a table of usable tiles. [PICKED_COLOR:6:13:0] is the color used for the crop's tile when harvested. It's in a foreground:background:brightness format. See [[color]] for the colors usable.

[PICKED_TILE:161][PICKED_COLOR:6:13:0]

[GROWDUR:300] is how long it takes for your crop to grow. There are 1008 growdur units in a season.<br>
[VALUE:2] Is the value of harvested plant (default 1). Appears to have no effect in version 0.31.

[GROWDUR:300][VALUE:2]

This defines the plant's alcohol states. [STATE_NAME_ADJ:ALL_SOLID:] is the frozen name, followed is the actual drink name, and then its boiling name. These are achieved by either Scorching or Freezing climates. [DISPLAY_COLOR] is, of course, color, and [EDIBLE_RAW] and [EDIBLE_COOKED] are saying you can drink the alcohol raw or cooked.

[USE_MATERIAL_TEMPLATE:DRINK:PLANT_ALCOHOL_TEMPLATE]
[STATE_NAME_ADJ:ALL_SOLID:frozen dwarven wine]
[STATE_NAME_ADJ:LIQUID:dwarven wine]
[STATE_NAME_ADJ:GAS:boiling dwarven wine]
[MATERIAL_VALUE:2]
[DISPLAY_COLOR:5:0:0]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PREFIX:NONE]
[DRINK:LOCAL_PLANT_MAT:DRINK]

After that we get our seed template:

[USE_MATERIAL_TEMPLATE:SEED:SEED_TEMPLATE]
[MATERIAL_VALUE:1]
[EDIBLE_VERMIN]
[EDIBLE_COOKED]
[SEED:plump helmet spawn:plump helmet spawn:4:0:1:LOCAL_PLANT_MAT:SEED]

And all this says is that the seeds may be eaten by vermin or cooked. Then it gives the name of our plant's seed, its plural name, its foreground, background, and brightness colors, followed by its seed material; said material should have [SEED_MAT] to permit proper stockpiling.

And finally for the last chunk we have this:

[SPRING][SUMMER][AUTUMN][WINTER]
[FREQUENCY:100]
[CLUSTERSIZE:5]
[PREFSTRING:rounded tops]
[WET][DRY]
[BIOME:SUBTERRANEAN_WATER]
[UNDERGROUND_DEPTH:1:3]
[SHRUB_TILE:142]
[DEAD_SHRUB_TILE:28]
[SHRUB_COLOR:5:13:0]
[DEAD_SHRUB_COLOR:5:6:0]

First we define what season(s) the plant may grow in, then we define how frequently this plant is generated in a particular area, followed by how many harvested crop items may come from 1 plant. [PREFSTRING:] is what your dwarves like about the plant, which in this case is the rounded tops. [WET][DRY] are the conditions under which the plant can grow. Wet means it can grow close to water, dry means it can grow away from water. This does not mean you can grow the plant on dry stone however. It is just for natural spawning of the plant.<br>
[BIOME] Is what biome the plant grows in. [UNDERGROUND_DEPTH:Minimum:Maximum] Is the highest and lowest cavern levels that the plant can appear in if its biome is subterranean. Dwarven civilizations will only export (via the embark screen or caravans) things that available at depth 1. Defaults to 0:0 (surface only).<br>
Lastly, [SHRUB_TILE] is the character used for the naturally spawning shrub of this plant, [DEAD_SHRUB] is the dead shrub character. [SHRUB_COLOR] Is the shrub's color, and [DEAD_SHRUB_COLOR] is, of course, the dead shrub's color.

While this may or may not look like a lot of tokens, it's very easy. Just copy an existing plant and edit it to your new plant.<br>
For the rest of the tokens, see [[plant token]].

=== Workshops ===

Workshops are raw-designed pretty differently from everything else in the game, being buildable structures rather than items or methods to gain items. However, they are fairly simple. For example, here's the raw for the [[soap maker's workshop]]:

[BUILDING_WORKSHOP:SOAP_MAKER]
[NAME:Soap Maker's Workshop]
[NAME_COLOR:7:0:1]
[DIM:3:3]
[WORK_LOCATION:2:2]
[BUILD_LABOR:SOAP_MAKER]
[BUILD_KEY:CUSTOM_SHIFT_S]
[BLOCK:1:0:0:1]
[BLOCK:2:0:0:1]
[BLOCK:3:0:0:0]
[TILE:0:1:' ':' ':150]
[TILE:0:2:' ':' ':'/']
[TILE:0:3:'-':' ':' ']
[COLOR:0:1:0:0:0:0:0:0:6:0:0]
[COLOR:0:2:0:0:0:0:0:0:6:0:0]
[COLOR:0:3:6:0:0:0:0:0:0:0:0]
[TILE:1:1:' ':' ':'=']
[TILE:1:2:'-':' ':8]
[TILE:1:3:' ':' ':150]
[COLOR:1:1:0:0:0:0:0:0:6:0:0]
[COLOR:1:2:6:0:0:0:0:0:6:0:0]
[COLOR:1:3:0:0:0:0:0:0:6:0:0]
[TILE:2:1:'-':' ':8]
[TILE:2:2:' ':' ':8]
[TILE:2:3:' ':150:' ']
[COLOR:2:1:6:0:0:0:0:0:6:0:0]
[COLOR:2:2:0:0:0:0:0:0:6:0:0]
[COLOR:2:3:0:0:0:6:0:0:0:0:0]
[TILE:3:1:150:' ':8]
[TILE:3:2:' ':' ':8]
[TILE:3:3:' ':240:' ']
[COLOR:3:1:6:0:0:0:0:0:6:7:0]
[COLOR:3:2:0:0:0:0:0:0:6:7:0]
[COLOR:3:3:0:0:0:7:0:1:0:0:0]
[BUILD_ITEM:1:BUCKET:NONE:NONE:NONE][EMPTY][CAN_USE_ARTIFACT]
[BUILD_ITEM:1:NONE:NONE:NONE:NONE][BUILDMAT][WORTHLESS_STONE_ONLY][CAN_USE_ARTIFACT]

A line-by-line breakdown:

[NAME:Soap Maker's Workshop]
[NAME_COLOR:7:0:1]

These are the name of the workshop ("Soap Maker's Workshop") and [[color]] of the workshop's name when examined with 'q' (White with a black background).

[DIM:3:3]
[WORK_LOCATION:2:2]

DIM refers to how large the workshop will be, in this case 3 wide, 3 tall. WORK_LOCATION tells where the creature using it (usually a dwarf) will work, numbered from the top right--in this case, 2:2, or the middle. Multiple work locations can be defined, even outside the dim.

[BUILD_LABOR:SOAP_MAKER]
[BUILD_KEY:CUSTOM_SHIFT_S]

These refer to the worker required to build it (soap maker) and the key used to build it in the workshop menu (capital S).

[BLOCK:1:0:0:1]
...
This is a bit more complex, and is where we get to the meaty part of workshop making--the tiles' properties. BLOCK refers to which tiles will be untraversable--1 means blocked, 0 means unblocked. The first number refers to row, and the next 3 refer to column, so 1:0:0:1 means that, on the first row, the first two tiles will be unblocked and the last will be blocked.

[TILE:0:1:' ':' ':150]
...
The TILE token tells which tile will go where. note, however, that there are 5 entries here instead of 4. The first number, in this case, refers to build stage, numbered from 0 to 3; 3 or 1 is fully built (depending on whether there are stages), 0 is just placed, and 2 is always an intermediate stage, while 1 is usually an intermediate stage. Whether 1 is an intermediate stage or not depends on if there are a 2 and 3 stage; if 2 and 3 exist, 1 will be intermediate. The second number and beyond are similar to BLOCK; however, instead of 1s and 0s, you must input tiles. The tiles themselves can be given in quotes (as in ' ') or given as a number, which can be looked up [[Tilesets|here]]. Here, we have 150, which is û.

[COLOR:1:1:0:0:0:0:0:0:6:0:0]
...
Color is as TILE, but with colors instead of tiles; however, colors are made up of 3 numbers each or MAT. MAT refers to the color of the material used to make it; the 3 numbers refer to foreground:background:foreground brightness, and can be looked up [[Color|here]]. For example, 4:2:1 will give you bright red with a dark green background.

[BUILD_ITEM:1:BUCKET:NONE:NONE:NONE][EMPTY][CAN_USE_ARTIFACT]
[BUILD_ITEM:1:NONE:NONE:NONE:NONE][BUILDMAT][WORTHLESS_STONE_ONLY][CAN_USE_ARTIFACT]
These refer to items required to build the building. These are in the same format as [[Reaction|reaction reagents and products]]--quantity:[[Item token|item]]:[[Material token|material]]. You'll learn more about those on the article about [[Reaction|reactions]], though. The second BUILD_ITEM is special-- it uses modifiers exclusively to determine its requirements. BUILDMAT refers to wood logs, wood blocks, stone boulders, and stone blocks; WORTHLESS_STONE_ONLY means it can't use economic stone; CAN_USE_ARTIFACT means that it... can use artifacts. EMPTY, in the bucket's case, means that the bucket must be empty.

More can be seen at the [[Building token|building tokens]] article.

=== Reactions ===

An in-depth guide for reactions is available [[Reactions|here]].

=== Materials ===

As we've seen when talking about creatures, materials are vital. Materials show up in two forms: material templates, which generally show up in creatures, and specific materials (designated as "inorganic"), which are (by default, at least) consigned purely to metal and stone types.

Let's take a look at METAL_TEMPLATE in material_template_default.txt. It's evident that most of the basic properties of metals are already defined in the template - it goes red and melts at a high enough temperature, it's heavy, and (as noted by the very bottom token) is a metal. We already know just how useful templates can be to creatures, and the same applies to other materials.

Now let's take a look at inorganic_metal.txt. You can see that the metals here refer to the templates, and, just like we did with creatures, then modify the properties of that template and expand upon it.

Finally, let's look at inorganic_stone_mineral.txt. Here we can see that in addition to the changes made to the template, there are also ENVIRONMENT tokens - these tell the game where to place these minerals during worldgen.

[[material definition token|Here's a list of material tokens]]. It should also help you out with any modifications you want to make regarding those creature modifications we were making a while back. See, it all ties together in the end. The beauty of the current materials system is that there's actually very little difference between, say, leather and iron - they're fundamentally the same thing, just with different properties, which is how things really should be.

== Examples ==

The Hydling by Mysteryguye (annotated, updated and separated into blocks by Putnam)
<pre>
[CREATURE:HYDLING]
[DESCRIPTION:A seven-headed small hairy thing, about the size of a dog. It is very loyal to its masters, and will promptly disembowel any enemy straying too close.]
This is the description that shows up in-game when viewing the creature.

[NAME:hydling:hydlings:hydlish] If there were a civ made of hydlings, it would appear as "hydlings" in the neighbors screen.

[CASTE_NAME:hydling:hydlings:hydlish]

[CREATURE_TILE:'='][COLOR:2:0:1] Will appear as a light green "=".

[PETVALUE:78][NATURAL] Creature is known to be naturally occurring by the game. Will cost 40 embark points to buy.

[LARGE_ROAMING] Will spawn outdoors, wandering around.

[COMMON_DOMESTIC][TRAINABLE][PET] Can be bought on embark as a pet, war animal, or hunting animal.

[BONECARN] Can eat meat and bones only--no vegetables.

[PREFSTRING:loyalty] Dwarves will like it for its loyalty.

[LARGE_PREDATOR] Will attack rather than flee.

[BODY:BASIC_2PARTBODY:7HEADNECKS:BASIC_FRONTLEGS:BASIC_REARLEGS:TAIL:2EYES:NOSE:2LUNGS:HEART:GUTS:ORGANS:THROAT:SPINE:BRAIN:SKULL:3TOES_FQ_REG:3TOES_RQ_REG:MOUTH:TONGUE:GENERIC_TEETH_WITH_FANGS:RIBCAGE]

Has a lower body, upper body, 4 legs, a tail, ten eyes, ten ears, five noses, two lungs, a heart, guts, a pancreas etc., and 5 heads with all that goes with those.

[BODYGLOSS:PAW] Feet will be called "paws"

[BODY_DETAIL_PLAN:STANDARD_MATERIALS] Declares the standard materials that most creatures' tissues are made of.

[BODY_DETAIL_PLAN:STANDARD_TISSUES] This declares the tissues that the creature's tissue layers are made of.

[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE] And this describes the tissue layers that the creature is made of.

[BODY_DETAIL_PLAN:BODY_HAIR_TISSUE_LAYERS:HAIR] Creature will be covered with a layer of fur.

[USE_MATERIAL_TEMPLATE:NAIL:NAIL_TEMPLATE] And it'll have nails.

[USE_TISSUE_TEMPLATE:NAIL:NAIL_TEMPLATE]

[TISSUE_LAYER:BY_CATEGORY:TOE:NAIL:FRONT] On the toe, specifically.

[SELECT_TISSUE_LAYER:HEART:BY_CATEGORY:HEART]
[PLUS_TISSUE_LAYER:SKIN:BY_CATEGORY:THROAT]
[TL_MAJOR_ARTERIES] Heart and throat--called above--will cause heavy bleeding if ruptured.

[BODY_DETAIL_PLAN:STANDARD_HEAD_POSITIONS] Places eyes, ears and what-have-you into their correct placement, so that you don't have people punching out eyes from behind.

[BODY_DETAIL_PLAN:HUMANOID_RIBCAGE_POSITIONS] Sets the ribcage as being around lungs and heart.

[USE_MATERIAL_TEMPLATE:SINEW:SINEW_TEMPLATE] Defines sinew so that...
[TENDONS:LOCAL_CREATURE_MAT:SINEW:200] Tendons...
[LIGAMENTS:LOCAL_CREATURE_MAT:SINEW:200] ...And ligaments can be defined.

[HAS_NERVES] Creature has nerves, and as such can be disabled by severing them.

[USE_MATERIAL_TEMPLATE:BLOOD:BLOOD_TEMPLATE] Defines the material BLOOD using the template BLOOD_TEMPLATE.
[BLOOD:LOCAL_CREATURE_MAT:BLOOD:LIQUID] Defines the creature's BLOOD as being made of the above-defined BLOOD material in a LIQUID state.

[CREATURE_CLASS:GENERAL_POISON] Creature can be affected by syndromes that affect GENERAL_POISON.

[GETS_WOUND_INFECTIONS] Pretty much self-explanatory. Creature can get infected from wounds.
[GETS_INFECTIONS_FROM_ROT] And from necrosis.

[USE_MATERIAL_TEMPLATE:PUS:PUS_TEMPLATE] Defines PUS using PUS_TEMPLATE.
[PUS:LOCAL_CREATURE_MAT:PUS:LIQUID] Defines PUS as being made of PUS.

[BODY_SIZE:0:0:1000] Creature will be 1000 cubic centimeters at birth...
[BODY_SIZE:1:0:12500] 12500 cubic centimeters at 1 year old...
[BODY_SIZE:2:0:30000] and 30000 cubic centimeters at 2.

[BODY_APPEARANCE_MODIFIER:LENGTH:90:95:98:100:102:105:110] Creature can be anywhere from 90% to 110% as long as others.
[BODY_APPEARANCE_MODIFIER:HEIGHT:90:95:98:100:102:105:110] As above, but with height.
[BODY_APPEARANCE_MODIFIER:BROADNESS:90:95:98:100:102:105:110] As above, but with broadness. This puts the minimum size of the creature (when fully grown) at 21870 and the maximum size at 39930.

[MAXAGE:20:30] Creature will die of old age between the ages of 20 and 30, no later than 30, no sooner than 20.

[CAN_DO_INTERACTION:MATERIAL_EMISSION] Creature can use the MATERIAL_EMISSION interaction.
[CDI:ADV_NAME:Hurl fireball] In adventurer mode, the MATERIAL_EMISSION interaction will appear as "Hurl fireball".
[CDI:USAGE_HINT:ATTACK] Creature will use MATERIAL_EMISSION when it's attacking, on creatures that it's attacking.
[CDI:BP_REQUIRED:BY_CATEGORY:HEAD] Creature must have at least one HEAD to use MATERIAL_EMISSION.
[CDI:FLOW:FIREBALL] The MATERIAL_EMISSION will shoot a fireball.
[CDI:TARGET:C:LINE_OF_SIGHT] The target for the emission--a location--must be within the line of sight of the Hydling.
[CDI:TARGET_RANGE:C:15] And must be, at most, 15 tiles away.
[CDI:MAX_TARGET_NUMBER:C:1] The hydling can only shoot at one target at a time...
[CDI:WAIT_PERIOD:30] and only every 30 ticks (3 tenths of a second at 100 FPS)

[ATTACK:BITE:CHILD_BODYPART_GROUP:BY_CATEGORY:HEAD:BY_CATEGORY:TOOTH] Defines a BITE attack that uses teeth.
[ATTACK_SKILL:BITE] Attack uses the BITE skill.
[ATTACK_VERB:nom:noms] "The Hydling noms the Elf in the left first toe, tearing the muscle!"
[ATTACK_CONTACT_PERC:100] Will use all of the tooth. Note that this can be more than 100.
[ATTACK_PENETRATION_PERC:100] Will sink the tooth all the way in. This can also be more than 100.
[ATTACK_FLAG_EDGE] Attack is an EDGE attack.
[ATTACK_PRIORITY:MAIN] Attack is of priority MAIN. Other option is SECOND.
[ATTACK_FLAG_CANLATCH] Attack can latch on.
[ATTACK_PREPARE_AND_RECOVER:3:3] Takes 3 ticks to wind up attack and 3 to recover from it.
[ATTACK_FLAG_INDEPENDENT_MULTIATTACK] Can use each head independently.

[ATTACK:SCRATCH:CHILD_TISSUE_LAYER_GROUP:BY_TYPE:STANCE:BY_CATEGORY:ALL:NAIL] As above, but for nail instead of teeth.
[ATTACK_SKILL:STANCE_STRIKE] Uses the kicking skill.
[ATTACK_VERB:slice:slices] "You slice the Elf in the left foot and the severed part sails off in an arc!"
[ATTACK_CONTACT_PERC:100] Uses the whole nail.
[ATTACK_PENETRATION_PERC:100] The whole nail goes in.
[ATTACK_FLAG_EDGE] Attack is an edge attack.
[ATTACK_PREPARE_AND_RECOVER:3:3]
[ATTACK_PRIORITY:SECOND]

[CHILD:1] Hydling will become an adult at 1 year old.

[GENERAL_CHILD_NAME:hydie:hydies] Children will appear as "hydies".

[DIURNAL] Is active during the daytime.

[HOMEOTHERM:10070] Has a body temperature of 102 Fahrenheit.

[APPLY_CREATURE_VARIATION:STANDARD_QUADRUPED_GAITS:900:730:561:351:1900:2900] Can run at 25 kph
[APPLY_CREATURE_VARIATION:STANDARD_SWIMMING_GAITS:3512:2634:1756:878:4900:6900] Can swim at 10 kph
[APPLY_CREATURE_VARIATION:STANDARD_CRAWLING_GAITS:6561:6115:5683:1755:7456:8567] Can crawl at 5 kph
[SWIMS_INNATE]Swims innately.

[CASTE:FEMALE] Defines a caste called FEMALE.
[FEMALE] FEMALE caste is female.

[CASTE:MALE] As above, but with male.
[MALE] See above.
</pre>

== Utilities ==
{{main|Utilities#Modding_tools|l1=Utilities § Modding_tools}}
There are several 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]].

== See Also ==
* [[Raw file]]
* [[Token]]

{{Category|Modding| }}
{{Category|Guides}}

Raw file

2018-04-28T21:37:23Z

Zilpin: /* Parsing */

{{Quality|Superior|02:10, 29 April 2013 (UTC)}}
{{av}}

'''Raw files''' are text files found in the '''raw/objects/''' subdirectory of Dwarf Fortress (used for [[world generation]]), as well as inside the [[saved game folder]] ('''data/save/<region name>/raw/objects/''') for already generated worlds. These files can be looked through to discover various specifics of game items, materials, and creatures, and can be changed to alter how the game behaves. They are sometimes referred to by players as just "the raws".

The '''raw/graphics''' subfolder of Dwarf Fortress is used to store user-customizable [[graphics set repository|graphics sets]]. The '''raw/interaction examples''' folder is absolutely useless and completely ignored by Dwarf Fortress.

Dwarf Fortress is not an open source program, so most [[modding]] of the game is limited to altering the raws or doing [[memory hacking]].

Duplicating the raw files can cause strange, difficult-to-diagnose problems, and even crashes in some cases.

==Syntax of raw files==

filename

[OBJECT:TYPE]

[TYPE:ID]
<...contents...>

ID is a unique identificator for your type to use (i.e. [CREATURE:DOG], ID=DOG or [ITEM:ITEM_WEAPON_SWORD], ID=ITEM_WEAPON_SWORD).

===Types of content===
*BODY — body parts and structures.
*BODY_DETAIL_PLAN — similar to CREATURE_VARIATION, but used for defining tokens related to body parts (specifically materials, tissues, the assignment thereof, and body part positions, relative sizes, etc.)
*BUILDING — custom workshops and smelters.
*CREATURE — [[creature]]s.
*CREATURE_VARIATION — variations that can be applied to creatures (e.g., making them giants, or anthropomorphic). Technically a series of tokens that are added to or removed from the creature (essentially a set of templated changes).
*DESCRIPTOR_COLOR (tag is COLOR) — named colours for use with DESCRIPTOR_PATTERN objects (other purposes unknown)
*DESCRIPTOR_PATTERN (tag is COLOR_PATTERN) — patterns with colour combinations for use with creatures.
*DESCRIPTOR_SHAPE (tag is SHAPE) — shapes with descriptions and variations. These are used for engravings.
*ENTITY — civilization types, with assigned race, language, culture, ethics, and social structure.
*GRAPHICS — graphic tiles for creatures. These are not found inside the raw/objects folder.
*INTERACTION — interaction definitions.
*INORGANIC — inorganic material definitions.
*ITEM — items ranging from ammunition to food types, has secondary types for the purposes of [TYPE:ID].
**ITEM_AMMO — ammunition for ranged weapons.
**ITEM_ARMOR — body clothing, including armour.
**ITEM_FOOD — prepared food definitions.
**ITEM_GLOVES — hand clothing, including armour.
**ITEM_HELM — head clothing, including armour.
**ITEM_INSTRUMENT — instrument definitions.
**ITEM_PANTS — lower body clothing, including armour.
**ITEM_SHIELD — shields.
**ITEM_SHOES — foot clothing, including armour.
**ITEM_SIEGEAMMO — ammunition for siege weapons that [[ballista]]e fire.
**ITEM_TOOL — multi-purpose items that can serve as a [[weapon]], food storage container, etc.
**ITEM_TOY — toy definitions.
**ITEM_TRAPCOMP — components that can be used in weapon traps (two special tags define trapcomps that can be used in other constructions: IS_SCREW and IS_SPIKE).
**ITEM_WEAPON — weapons that are used by soldiers, as well as digging tools.
*LANGUAGE — word definitions for the languages used by ENTITY objects.
**Entries beginning with [SYMBOL:ID] sort words into symbolic/poetic groups to be referenced by ENTITY preferences.
**Entries beginning with [WORD:ID] define words and their alternate forms (in English).
*MATERIAL_TEMPLATE — definitions of information common to groups of materials (referenced all over the place).
*PLANT — definitions of plants, their materials, and their derivatives.
*REACTION — reactions/custom workshop jobs (turn items into other items through dwarven or adventurer effort).
*TISSUE_TEMPLATE — defines templated tissues for use with BODY_DETAIL_PLAN objects or in creatures.

Usually empty lines are used to divide different types of structures like the file name and [OBJECT:] or different entries, however everything which is not a token besides the 1st string (which is the filename) is understood as comments and is not considered.

The tokens are enclosed in square brackets ([TOKEN:VALUES]).

When a world is generated, the raw files are copied from <game folder>/raw/ to <game folder>/data/save/REGION/raw/. It is currently unknown how much these can then be changed without breaking the save.

A list of tokens can be seen at [[:Category:Tokens]].

== Parsing ==
The order that Dwarf Fortress parses raw files is determined by the first line of the raw file (''not'' necessarily the filename). This parsing order is important for certain tags such as [COPY_TAGS_FROM], but not for most other tags.

The load order (recorded by logging DF 0.44.09 file activity in Windows 10) follows the following pattern:

language_*
descriptor_shape_*
descriptor_color_*
descriptor_pattern_*
material_template_*
inorganic_*
plant_*
tissue_template_*
item_*
building_*
b_detail_plan_*
body_*
c_variation_*
creature_*
entity_*
reaction_*
interaction_*

Therefore, vanilla DF 0.44.09 loads RAW files in the following order:

language_DWARF.txt
language_ELF.txt
language_GOBLIN.txt
language_HUMAN.txt
language_SYM.txt
language_words.txt
descriptor_shape_standard.txt
descriptor_color_standard.txt
descriptor_pattern_iris_eye.txt
descriptor_pattern_pupil_eye.txt
descriptor_pattern_special.txt
material_template_default.txt
inorganic_metal.txt
inorganic_other.txt
inorganic_stone_gem.txt
inorganic_stone_layer.txt
inorganic_stone_mineral.txt
inorganic_stone_soil.txt
plant_crops.txt
plant_garden.txt
plant_grasses.txt
plant_new_trees.txt
plant_standard.txt
tissue_template_default.txt
item_ammo.txt
item_armor.txt
item_food.txt
item_gloves.txt
item_helm.txt
item_pants.txt
item_shield.txt
item_shoes.txt
item_siegeammo.txt
item_tool.txt
item_toy.txt
item_trapcomp.txt
item_weapon.txt
building_custom.txt
b_detail_plan_default.txt
body_default.txt
body_rcp.txt
c_variation_default.txt
creature_amphibians.txt
creature_annelids.txt
creature_birds.txt
creature_birds_new.txt
creature_bug_slug_new.txt
creature_desert_new.txt
creature_domestic.txt
creature_equipment.txt
creature_fanciful.txt
creature_insects.txt
creature_large_mountain.txt
creature_large_ocean.txt
creature_large_riverlake.txt
creature_large_temperate.txt
creature_large_tropical.txt
creature_large_tundra.txt
creature_mountain_new.txt
creature_next_underground.txt
creature_ocean_new.txt
creature_other.txt
creature_reptiles.txt
creature_riverlakepool_new.txt
creature_small_mammals.txt
creature_small_mammal_new.txt
creature_small_ocean.txt
creature_small_riverlake.txt
creature_standard.txt
creature_subterranean.txt
creature_temperate_new.txt
creature_tropical_new.txt
creature_tundra_taiga_new.txt
entity_default.txt
reaction_adv_carpenter.txt
reaction_other.txt
reaction_smelter.txt
interaction_standard.txt

[[Category:Files]]
{{Category|Modding}}

v0.34:Minecart

2012-09-28T23:21:16Z

Zilpin: /* Capacity */

{{quality|Fine|22:04, 14 May 2012 (UTC)}}{{av}}{{Buggy}}
A '''minecart''' is a [[tool]] used mostly for [[hauling]]. It is made of [[wood]] at a [[carpenter's workshop]], or [[metal]] at a [[metalsmith's forge]]. Minecarts store up to five times as many items as [[wheelbarrow]]s and are quite a bit faster than hauling dwarves, but have the disadvantage of requiring a dedicated track network and a complex route setup. Minecart tracks also take up a lot of space, may be complicated to construct, and can be resource-intensive.

Just like wheelbarrows, minecarts are considered [[item]]s and are stored in a [[furniture]] [[stockpile]]. Despite their five times greater capacity, they are only one third larger than wheelbarrows and are identical in base [[item value|value]] when made from the same [[material]] (the value may differ due to the [[item quality]]). As items, [[thief|thieves]] or even mischievous animals can steal minecarts, even when moving on a track. If a minecart is moving fast enough, or if it has a rider, thieves will be unable to steal the minecarts.

Although most of the utility of minecarts is in [[fortress mode]], an [[adventure mode|adventurer]] can also ride in a minecart. Adventurers can also pick up and relocate minecarts.

Since their introduction in version 0.34.08, a new [[hauling]] [[labor]] preference was added to all dwarves, called "Push/Haul Vehicles", turned on by default.

The invention of minecarts revolutionized the [[minecart logic|Science of Dwarfputing]] by enabling smaller, faster logic systems to be built.

== Track ==
Tracks can be built in two ways:
*A single-tile wide strip of natural stone can be designated to be [[Engraver|carved]] (with {{K|d}} {{k|T}}), which will create a straight two-way track. The creation of corners, crossings, and T-junctions is as simple as designating another strip of track that overlaps an existant or newly-designated track. Engraved tracks are removed by [[smoothing]] the rock they're on, which results in a smooth floor (that can be re-engraved if necessary), or by building a [[floor]] on top and subsequently removing it.
**The carving of natural ramps is a little more confusing: to carve a two-way track on a ramp (natural only, does not work on constructed ramps), you must designate the ramp '''and one square beyond''' in the direction you want the track to go. For the side of the ramp square you want to head upward, there '''must''' be either a natural or constructed wall in the square next to it, otherwise the game assumes you are trying to carve it on the same level -- this can result in the track being carved underneath a door or other object. If you have accidentally done this, you can correct it by smoothing the ramp and constructing a single square of wall next to it, then re-carving the ramp correctly. (However, the wall must stay there permanently, removing it will disconnect the track.)

*Tracks can also be built as regular [[construction]]s (through {{K|b}} {{K|C}} {{K|T}}). This method is resource-expensive, since each track tile requires one stone, [[bar]], or [[block]] for construction, and time-consuming, since you can't designate strips larger than 10 tiles at a time. Corners, crossings, T-junctions, and ramps also have to be designated individually. However, it is usually the only way to build tracks above ground (barring the [[Obsidian farming|creation of obsidian]]), and the only way to create one-way tracks. Constructed tracks are designated for removal like any regular construction; be aware that removing track ramps built on top of natural ones will also remove the original ramp, leaving a flat floor.

Every track, when complete, will designate the tile with a low-priority [[traffic|traffic order]]. This reduces the odds of dwarves walking into a high-speed minecart; however, it should be noted that pets and livestock ignore traffic orders. Note that removing the track doesn't reset that tile back to normal traffic priority, so you may wish to manually clean up traffic designation afterward. Also note that bridges that are used as tracks don't have their traffic priority changed automatically (since they're just normal bridges), which could cause dwarves to pathfind normally through dangerous minecart entrances in your fort's walls if you're not careful.

As constructions or tile features, [[door]]s and other furniture can be built on tracks. A [[door]] or [[floodgate]] can be turned on or off by a [[lever]], effectively controlling the flow of automated minecarts. This may be dangerous, however. 

[[Bridge]]s can also act as tracks, but only if they're lowered or not retracted. This property can enable levers to turn tracks on and off. However, care should be taken to ensure that such bridges are never operated while a cart is on top of them, as the cart will be flung off the track. It's worth noting that it's often faster, and cheaper, to construct large bridges than long sections of constructed track. It's also worth noting that bridges do not automatically have a low pathfinding traffic priority assigned to them, however.

== Hauling route ==
The proper setting up of routes is essential for a working rail system. Routes, stops, departure conditions and stockpile links are managed from the {{k|h}}auling menu.

=== Route ===
New routes are created with the {{k|h}}auling key. Existing ones can be removed (without confirmation) with the {{k|x}} key, and also {{k|n}}icknamed. Before operating, the route must have at least one {{k|v}}ehicle assigned to it (this can be done with either the route or a stop selected). Assigning a full minecart to a route may result in a slow hauling job if the contents are heavy.

=== Stop ===
Stops are designated by moving the cursor on top of the desired tile and pressing the {{k|s}} key afterwards. They can be removed with and nicknamed with the same hotkeys as routes. Stops can also be reordered with the {{k|p}}romote key. Without a definition, however, a stop is fairly useless: pressing the {{k|Enter}} key with a stop selected in the route menu opens its stop definition screen, from which departure conditions and stockpile links can be set up.

==== Stockpile links ====
By placing the cursor on top of a stockpile and using {{k|s}}, you can create stockpile links for a track stop. Links can also be redefined by selecting them, placing the cursor over a different stockpile, and pressing {{k|p}}.

==== Departure condition ====
Departure conditions involve setting conditions in which the minecart will leave on the route. Each condition includes:
# A departure mode (Guide, Ride or Push).
# A departure direction (NSEW).
# A timer, before which the departure condition cannot be met.
# Conditions on the amount of items in the cart.
Departure conditions are created with the {{k|n}} key. A new departure condition will read: "guide north immediately when empty of desired items". This condition can be changed between basic presets with {{k|c}}. "Advanced" mode ({{k|C}}) allows for more precise control over departure conditions: fine tuning the percentage from 0 to 100 in 25% steps ({{k|f}} and {{k|F}}), switching it being either the maximum or the minimum amount of items for the condition to be met ({{k|m}}), and whether the cart accepts all or only a specific set of items ({{k|l}}). Common to both screens are the departure mode ({{k|p}}, Push, Ride or Guide), {{k|d}}irection, and timer ({{k|t}} and {{k|T}}) options.

To have a cart only carry a specific set of items, the stop can be set to only carry "desired" items, opening the selection screen with the {{k|Enter}} key while having said stop condition selected, and toggling as desired, or it can simply be linked to a restricted stockpile and set to depart with any items.

== Physics ==


Minecart physics depend greatly on the departure mode set in the route stop conditions.

When set to "Push" or "Ride", minecarts will move according to the regular laws of momentum, gaining speed when going downhill, losing it slowly due to friction when on a flat plane, and more quickly when going uphill. In these modes, minecarts will move along the track in a straight line until they either run off the tracks or encounter a turn. A minecart will continue straight at a T junction if possible but if it is not possible the track is treated as a dead end and may jump track. The cart's behavior also depends on the weight of its contents (including fluids and dwarves): heavily loaded carts are harder to accelerate and to stop, and gain more momentum when going downhill. In either case, dwarves can not push nor ride an unpowered cart up a ramp, bouncing back the direction it came. At best, this is a waste of time; at worst, it will give your cart-pushing dwarf a [[fun|fun surprise]]. To solve this, the player can either use Rollers (see below) or set the cart to be Guided.

When set to "Guide", minecarts seem to ignore all laws of physics. They:
*Ignore the weight of any and all items inside. Therefore:
**Move at the speed of the dwarf that is guiding them. It is thus recommended to pick the most [[attribute#Agility|agile]] of your dwarves for cart-guiding tasks.
*Ignore working rollers.
*Will ''not'' collide with other guided carts even when a full frontal collision would be expected.
*Will go up ramps like nobody's business.
This is therefore the recommended method of transport for simple non-powered rail systems, despite it diverting a dwarf from other, potentially more important tasks.

Some samples with behavior:

A <-> B A <-> C A <-> B
B╥ B╥ B╥
║ ║ ║
A╞══╝ A╞══╩══╡C A╞══╬╗
You can only go A->B ╚╝
Works when the cart Works
is in Guide mode.

In the second example above, if you attempt to "Push" from B to A or C, [[Fun|''the cart will go careening off of the tracks'']].

=== Skipping ===
If a minecart is moving fast enough, it can skip over [[water]] or [[magma]], making splashes of [[mist]] (or [[magma mist]]) as it attempts to move on them horizontally. This horizontal movement is independent of the minecart and its content's [[weight]].

=== Track Jumping ===
If a minecart encounters the end of the track or a T junction where it can not continue straight it may jump off of the track if it is going fast enough. The minecart will now continue in a straight line until in encounters an obstacle, slows to a stop, or encounters another (properly aligned) Track. An escaped minecart will follow another track even if it is a corner.

=== Falling ===
When falling, a minecart appears to cause no damage upon collision with a creature, possibly to allow cart "stacking" across Z-levels. {{verify}} A dwarf riding in a minecart that is dropped multiple z-levels suffers normal fall damage. Minecarts can fall through up/down stairs.

=== Stacking ===
If a minecart lands on another minecart in exactly the perfect orientation and time, they may form a stack (effectively a pillar) of minecarts. This pillar, aside from the [[megaprojects]] uses possible, is also useful for [[trap design]] with minecarts as the weaponry.

The location of the upper minecarts, above what seems to be thin air, can be confusing. These minecarts generally need to be struck with another minecart to move out, or have their support removed. The latter option can be somewhat dangerous, however.

=== Danger ===
Minecarts are not without [[Fun|danger]]. Although designating a track automatically sets the [[traffic]] designation to low, dwarves ''may'' still walk on them, and [[creature]]s ignore traffic designations altogether. If an unlucky dwarf or creature fails to [[dodger|dodge]] a minecart, they can be injured. Most of this danger can be avoided by setting the minecart {{k|h}}auling commands to guide instead of push or ride, as dwarves guiding minecarts will ignore traffic restrictions, by [[pasture|pasturing]] domestic animals, and preventing the access of other creatures to the tracks.

Danger does not always involve living victims: careless route designation can also result in minecarts careening off tracks or colliding with each other. If this occurs, the [[item]]s may be scattered; this can cause even more hauling jobs than the minecart aimed to eliminate. Even <s>better</s> worse, scattered items, especially [[weapon]]s, can injure passing [[dwarf|dwarves]] or other [[creature]]s; in the words of Toady One the Great, "Accidental grapeshotting of the dining room should be possible now."

Of course, the danger of using minecarts means they can also be used as weapons by imaginative players.

== Automation ==

=== Track stop ===
Track stops are constructions that allow further automation of minecart systems via adjustable features such as braking by friction and automatic dumping of contents. They can be built from logs, bars and blocks through {{K|b}} {{K|C}} {{K|S}}; friction amount, dumping toggle and dumping direction must be set '''before''' construction, and these settings can be neither changed nor seen thereafter; however, track stops can be linked to [[pressure plate]]s or [[lever]]s to toggle friction upon activation. Take care not to set track stops at a loading site to dump their contents, or dwarves will never be able to fill the cart.

Track stops are not mandatory; in fact, their main use is in automated rail systems, to stop and hold extremely fast-moving minecarts or to dump contents mid-way without stopping. However, even in basic rail systems it can be useful to set a track stop to dump items: this saves time that dwarves would otherwise spend in removing items from the cart, time that is better spent driving the cart back to where it's needed.

If a stockpile is built on the square that a track stop is set to dump to, it can act as a [[ Exploit#Quantum_stockpiles|quantum stockpile]] and any items dumped from a minecart that match the storage settings of the stockpile will remain there and accumulate. Normally trackstops are built on top of existing track to operate on moving minecarts, but they can also be used without tracks to create [[Exploit#The_Minecart_Stop|automatic quantum stockpiles]] (see also [[#Example|route example]]).

Counter-intuitive to their construction method, track stops are considered [[building]]s and must be removed by {{k|q}} {{k|x}}.

=== Roller ===
A '''roller''' is a [[power]]ed [[machine component]] for the automated propulsion of minecarts. They are built with {{K|b}} {{K|M}} {{K|r}}, requiring a [[mechanic]], one or more [[mechanism]]s and a [[rope]]. Rollers are very useful to maintain a cart's momentum along long routes, to get them to climb Z-levels without dwarfpower involved, and to get them to reach speeds unattainable by guiding dwarves. These devices are variable-length, variable-direction, and variable-power, all traits that can be set at construction time; at the highest speed, a roller uses two units of power per tile it is long.

Rollers may apparently be placed directly on ramps to help pull carts up Z levels. Currently rollers can only be placed on ramps if it would result in it being connected to a preexisting power connection (gears, axles, or pumps). Rollers will transfer power along their sides but not from their front or back (the edges on the track).

Care must be taken in [[glacier]]s and other extremely cold [[biome]]s, since rollers can be rendered inoperable when exposed to freezing [[temperature]]s.

Because of their one-way nature, rollers are unsuitable for most two-way minecart tracks. However, a minecart set to be ''guided'' is not affected by rollers at all — this allows a one-way track to be used in both directions. In addition, rollers do not affect minecarts when disengaged: switching mechanisms (such as a [[pressure plate]] attached to powering [[gear assembly]]) can be used to create complex paths.

Rollers cannot be powered from above.

=== Switching ===


A rudimentary track switch can be constructed by building a T-junction as illustrated below.

B╥ B╥
║ ║
║ -> ║
║ ║
A╞════╚════╡C A╞════R════╡C

The 'R' is roller pushing from East to West.
If the cart is pushed East from the stop at 'A' while the roller is activated, it will arrive at 'B'. If the roller is not running, it will arrive at 'C'.

This switch has a disadvantage - it requires power. An alternative non-powered solution uses controlled derailment, or a connecting bridge.

B╥
║
║
A╞════╝D ════╡C

Here the track between A and C is not continuous. The only continuous track is A->B, with a corner (not a T section). Fast moving carts will tend to derail at D and rejoin the track to C. Placing a door at D will prevent the derailment, so the cart continues to B. The door is operated by mechanisms elsewhere (typically, a lever, but some fun can be had with pressure plates).

If carts are moving too slowly to reliably derail at the corner, a retractable bridge may be used as a connector between A and C.
B╥
║
║
A╞════bbb════╡C
The bridge must overlap the corner so that it acts as if a T junction track when extended. When retracted, the corner reappears, so the slower carts will continue to B.

=== Controlling Speed ===


Minecarts can reach extremely high speeds, especially when descending multiple Z-levels. A minecart will derail at a track corner if it's speed exceeds 0.5 m/s (here m/s really means tiles per step), '''unless''' the route in the direction of travel is blocked:

Will derail at > 0.5 m/s:

in ═╗->
out

Will not derail at > 0.5 m/s:

in ═╗O
|
v
out

O is wall.

This behavior can be used to build a "speed limiter", that will ensure that when a minecart exits it is traveling below derail speed:

OOOO
in ═╔═╗O
out ═╬═╝O
O╚S╝O
OOOOO

O is wall, S is a Track Stop set to High Friction or lower. If the minecart is traveling below derailment speed it will not be effected.

== Example ==

Let's construct a simple minecart route. This route will move stone blocks from an input stockpile to an output stockpile. We'll begin by creating the stockpiles:

[[File:minecart-example-1.png|Stockpiles designated.]]

The input stockpile is on the left; the output stockpile is on the right. We'll be moving blocks from left to right. Disable bins in both stockpiles, and set the input stockpile to accept only from links. Then make the stockpile take from the mason's workshop where the blocks are being produced.

Next, carve the track:

[[File:minecart-example-2.png|Track carving designation.]]

Note that the ends of the designation are uniquely shaped; this is automatic, and not anything you need to control. Now, wait for your engravers to come along and carve the track into the stone. (Your haulers will probably also fill up the input stockpile while you wait.)

In addition, while we're waiting for that to happen, we'll build an iron minecart in the forge.

[[File:minecart-example-3.png|Track carved.]]

When the track has been carved, it will look like the above (the track will be solid instead of flashing). Now, order a track stop to be constructed next to the output stockpile:

{|
| [[File:minecart-example-4.png|Track stop designation.]]
| [[File:minecart-example-5.png|Select dumping direction.]]
|}

You must press {{k|d}} three times to select the dumping direction ''before'' placing the track stop. We want our blocks to be dumped into the output stockpile east of the track stop. Then wait for a mechanic to come along and build the track stop.

[[File:minecart-example-6.png|Track stop constructed.]]

Now we'll define the actual ''route''. This is done in the {{k|h}}auling menu. Press {{k|r}} to begin defining a route. Next, move the cursor to the input end of the track, and then press {{k|s}} to define the first stop:

{|
| [[File:minecart-example-7.png|Stop 1 designation.]]
| [[File:minecart-example-8.png|Route definition, in progress.]]
|}

Move the cursor again, to the output end of the track, and press {{k|s}} again to define the second stop:

{|
| [[File:minecart-example-9.png|Stop 2 designation.]]
| [[File:minecart-example-10.png|Route definition, two stops.]]
|-
|
| [[File:minecart-example-11.png|Stops are not defined yet.]]
|}

There are several user interface features to note at this point. The stops have been positioned, but they haven't been ''defined'' yet, so there is a warning ! symbol by each of them. In the lower right corner, we see what the ! means. Also, note that the second stop is labeled in white, while the other two lines are grey. The white text is a selection indicator, and can be moved up and down by pressing {{k|+}}/{{k|-}}.

Next we need to define what our stops do. We want the minecart to be filled with blocks at the first stop, then travel to the second stop where it will dump its cargo, and then return. Press {{k|-}} to move the selection up to stop 1, and {{k|Enter}} to open it up. By default, the stop has three conditions:

[[File:minecart-example-12.png|Default stop definition.]]

We don't want any of these, so press {{k|x}} three times to delete them. This leaves us with a blank stop. Now we can add the conditions we actually want. Press {{k|n}} to begin adding the first condition, then {{k|d}} twice to change the direction from north to east. Then press {{k|c}} to change the condition from empty to full. This will instruct the minecart to be guided east when full of desired items.

To set the desired items, we create a stockpile link. Press {{k|s}}, then move the cursor to the input stockpile, then press {{k|p}} to select that stockpile. Now press {{k|Enter}}; this opens up a selection screen that resembles the stockpile customization screen. Move down to Blocks, {{k|e}}nable them, then (if you wish) restrict it to stone blocks.

When you've done all that, stop 1 should look like this:

[[File:minecart-example-13.png|Stop 1, defined.]]

Stop 2 is much simpler. All we need to do is have the minecart return to the input stop. So, make a condition and change the direction:

[[File:minecart-example-14.png|Stop 2, defined.]]

Finally, we just have to assign our minecart. Go back to the route definition screen, and press {{k|v}}. Select the minecart, and press {{k|Enter}}.

Now we've got everything set up:

[[File:minecart-example-15.png|Route, fully defined.]]

The V is red because the minecart hasn't been moved onto the track yet. Some dwarf will have to haul it from the forge to the first stop, by hand; this will take a while, especially if the forge is far away.

Once the minecart is in place, dwarves should fill it with blocks from the input stockpile, which will in turn be filled with blocks from the workshop where your mason has been toiling dutifully. When the minecart is full, the blocks will be dumped into the 1x1 stockpile on the right. Automatic quantum dumping!

== Troubleshooting ==

Because of the complexity of the system, all but the most careful and experienced minecart users will encounter issues. Most route issues can be diagnosed and fixed from the {{k|h}}auling menu.

'''Symptom:''' {{DFtext|! Set dir/connect track|6:1}} message appears to the right of one or more stops
<br>'''Possible Causes:'''
* The departure direction of the stop might be invalid. Edit the stop using {{k|Enter}} and press{{k|d}} until it is pointing in a valid direction.
* The track stop might not be built on top of a track. The track stop must be deconstructed to remedy this issue.
* Your track might not be built correctly. Make sure all connected tracks between destinations are not one-way tracks.
** This can be especially confusing with ramps. To carve a two-way track on a (natural) ramp, you must designate the ramp <b>and one square beyond</b> in the direction you want the track to go.
** Ramps '''must''' have a solid block on the side opposite to the track, or they will neither work nor be marked as "unusable". The solid block can be natural or constructed.
* The desired/kept items might not be configured correctly.

'''Symptom:''' The status '''0% <span style="color:#00dd00;">V</span>''' always appears to the right of one stop.
<br>'''Possible Causes:'''
* The stop may not be set to take from a stockpile. Edit the Stop using {{k|Enter}} and make sure you see a message like "Take from Stockpile #1".
* The take conditions must correspond with the contents of the stockpile.
* The track stop may be set to dump. A track stop set to dump cannot be filled. You must either set the stop to a time-based departure or deconstruct the track stop and rebuild it without dumping.
* Make sure the minecart itself has not been designated to be dumped (such as when using mass-dump).

== Capacity ==
Minecarts have five times the capacity of wheelbarrows, which is an enormous amount. A single minecart can carry 2500 rolls of [[cloth]], for example, or even a hundred stone blocks. Unfortunately, loading 2500 [[stone|boulder]]s onto a minecart is not possible (five boulders fit).

A glumprong minecart full with 5 pitchblende boulders weighs 3848Γ (the cart alone is 48Γ).<br />
A gold minecart is 772Γ, full of gold bars is 10398Γ.<br />
An platinum minecart weighs 856Γ.<br />
If slade minecarts were possible, they would weigh 8000Γ empty.<br />

[[Water]] and [[magma]] can also be loaded into minecarts by submerging them to a depth of at least 6/7, and dumped by a constructed track stop. Loading fluids onto minecarts can be difficult because their weight can slow the minecart down greatly. Curiously, filling a minecart with magma does not injure a dwarf ''riding'' it. A minecart will hold enough magma to increase the depth of a single tile by 2. This amount is listed as 833 units, which weigh 999Γ. An iron or steel cart filled with magma weighs 1313Γ. An adamantine one weighs 1007Γ.

The capacity in a minecart affects whether a [[pressure plate]] triggers or not, based on the pressure plate's setting.

== Bugs ==

*If you set up lots of routes and stops and then resize your screen, the list will scroll off-screen in the hauling menu. You can still navigate the list with keyboard commands, but cannot see the stop/route name. This will be fixed in the next release.
*A dwarf will drop its [[child|baby]], if it has one, when boarding a minecart set to be ridden.
*Tracks block wagon access to trade depots.{{bug|6040}}
*Dwarves cannot guide a minecart through an unlocked door unless another dwarf opens the door{{bug|6056}}

{{Category|Fortress mode}}
{{Category|Interface}}

[[ru:Minecart]]

v0.34:Minecart

2012-09-28T23:03:40Z

Zilpin: /* Capacity */

{{quality|Fine|22:04, 14 May 2012 (UTC)}}{{av}}{{Buggy}}
A '''minecart''' is a [[tool]] used mostly for [[hauling]]. It is made of [[wood]] at a [[carpenter's workshop]], or [[metal]] at a [[metalsmith's forge]]. Minecarts store up to five times as many items as [[wheelbarrow]]s and are quite a bit faster than hauling dwarves, but have the disadvantage of requiring a dedicated track network and a complex route setup. Minecart tracks also take up a lot of space, may be complicated to construct, and can be resource-intensive.

Just like wheelbarrows, minecarts are considered [[item]]s and are stored in a [[furniture]] [[stockpile]]. Despite their five times greater capacity, they are only one third larger than wheelbarrows and are identical in base [[item value|value]] when made from the same [[material]] (the value may differ due to the [[item quality]]). As items, [[thief|thieves]] or even mischievous animals can steal minecarts, even when moving on a track. If a minecart is moving fast enough, or if it has a rider, thieves will be unable to steal the minecarts.

Although most of the utility of minecarts is in [[fortress mode]], an [[adventure mode|adventurer]] can also ride in a minecart. Adventurers can also pick up and relocate minecarts.

Since their introduction in version 0.34.08, a new [[hauling]] [[labor]] preference was added to all dwarves, called "Push/Haul Vehicles", turned on by default.

The invention of minecarts revolutionized the [[minecart logic|Science of Dwarfputing]] by enabling smaller, faster logic systems to be built.

== Track ==
Tracks can be built in two ways:
*A single-tile wide strip of natural stone can be designated to be [[Engraver|carved]] (with {{K|d}} {{k|T}}), which will create a straight two-way track. The creation of corners, crossings, and T-junctions is as simple as designating another strip of track that overlaps an existant or newly-designated track. Engraved tracks are removed by [[smoothing]] the rock they're on, which results in a smooth floor (that can be re-engraved if necessary), or by building a [[floor]] on top and subsequently removing it.
**The carving of natural ramps is a little more confusing: to carve a two-way track on a ramp (natural only, does not work on constructed ramps), you must designate the ramp '''and one square beyond''' in the direction you want the track to go. For the side of the ramp square you want to head upward, there '''must''' be either a natural or constructed wall in the square next to it, otherwise the game assumes you are trying to carve it on the same level -- this can result in the track being carved underneath a door or other object. If you have accidentally done this, you can correct it by smoothing the ramp and constructing a single square of wall next to it, then re-carving the ramp correctly. (However, the wall must stay there permanently, removing it will disconnect the track.)

*Tracks can also be built as regular [[construction]]s (through {{K|b}} {{K|C}} {{K|T}}). This method is resource-expensive, since each track tile requires one stone, [[bar]], or [[block]] for construction, and time-consuming, since you can't designate strips larger than 10 tiles at a time. Corners, crossings, T-junctions, and ramps also have to be designated individually. However, it is usually the only way to build tracks above ground (barring the [[Obsidian farming|creation of obsidian]]), and the only way to create one-way tracks. Constructed tracks are designated for removal like any regular construction; be aware that removing track ramps built on top of natural ones will also remove the original ramp, leaving a flat floor.

Every track, when complete, will designate the tile with a low-priority [[traffic|traffic order]]. This reduces the odds of dwarves walking into a high-speed minecart; however, it should be noted that pets and livestock ignore traffic orders. Note that removing the track doesn't reset that tile back to normal traffic priority, so you may wish to manually clean up traffic designation afterward. Also note that bridges that are used as tracks don't have their traffic priority changed automatically (since they're just normal bridges), which could cause dwarves to pathfind normally through dangerous minecart entrances in your fort's walls if you're not careful.

As constructions or tile features, [[door]]s and other furniture can be built on tracks. A [[door]] or [[floodgate]] can be turned on or off by a [[lever]], effectively controlling the flow of automated minecarts. This may be dangerous, however. 

[[Bridge]]s can also act as tracks, but only if they're lowered or not retracted. This property can enable levers to turn tracks on and off. However, care should be taken to ensure that such bridges are never operated while a cart is on top of them, as the cart will be flung off the track. It's worth noting that it's often faster, and cheaper, to construct large bridges than long sections of constructed track. It's also worth noting that bridges do not automatically have a low pathfinding traffic priority assigned to them, however.

== Hauling route ==
The proper setting up of routes is essential for a working rail system. Routes, stops, departure conditions and stockpile links are managed from the {{k|h}}auling menu.

=== Route ===
New routes are created with the {{k|h}}auling key. Existing ones can be removed (without confirmation) with the {{k|x}} key, and also {{k|n}}icknamed. Before operating, the route must have at least one {{k|v}}ehicle assigned to it (this can be done with either the route or a stop selected). Assigning a full minecart to a route may result in a slow hauling job if the contents are heavy.

=== Stop ===
Stops are designated by moving the cursor on top of the desired tile and pressing the {{k|s}} key afterwards. They can be removed with and nicknamed with the same hotkeys as routes. Stops can also be reordered with the {{k|p}}romote key. Without a definition, however, a stop is fairly useless: pressing the {{k|Enter}} key with a stop selected in the route menu opens its stop definition screen, from which departure conditions and stockpile links can be set up.

==== Stockpile links ====
By placing the cursor on top of a stockpile and using {{k|s}}, you can create stockpile links for a track stop. Links can also be redefined by selecting them, placing the cursor over a different stockpile, and pressing {{k|p}}.

==== Departure condition ====
Departure conditions involve setting conditions in which the minecart will leave on the route. Each condition includes:
# A departure mode (Guide, Ride or Push).
# A departure direction (NSEW).
# A timer, before which the departure condition cannot be met.
# Conditions on the amount of items in the cart.
Departure conditions are created with the {{k|n}} key. A new departure condition will read: "guide north immediately when empty of desired items". This condition can be changed between basic presets with {{k|c}}. "Advanced" mode ({{k|C}}) allows for more precise control over departure conditions: fine tuning the percentage from 0 to 100 in 25% steps ({{k|f}} and {{k|F}}), switching it being either the maximum or the minimum amount of items for the condition to be met ({{k|m}}), and whether the cart accepts all or only a specific set of items ({{k|l}}). Common to both screens are the departure mode ({{k|p}}, Push, Ride or Guide), {{k|d}}irection, and timer ({{k|t}} and {{k|T}}) options.

To have a cart only carry a specific set of items, the stop can be set to only carry "desired" items, opening the selection screen with the {{k|Enter}} key while having said stop condition selected, and toggling as desired, or it can simply be linked to a restricted stockpile and set to depart with any items.

== Physics ==


Minecart physics depend greatly on the departure mode set in the route stop conditions.

When set to "Push" or "Ride", minecarts will move according to the regular laws of momentum, gaining speed when going downhill, losing it slowly due to friction when on a flat plane, and more quickly when going uphill. In these modes, minecarts will move along the track in a straight line until they either run off the tracks or encounter a turn. A minecart will continue straight at a T junction if possible but if it is not possible the track is treated as a dead end and may jump track. The cart's behavior also depends on the weight of its contents (including fluids and dwarves): heavily loaded carts are harder to accelerate and to stop, and gain more momentum when going downhill. In either case, dwarves can not push nor ride an unpowered cart up a ramp, bouncing back the direction it came. At best, this is a waste of time; at worst, it will give your cart-pushing dwarf a [[fun|fun surprise]]. To solve this, the player can either use Rollers (see below) or set the cart to be Guided.

When set to "Guide", minecarts seem to ignore all laws of physics. They:
*Ignore the weight of any and all items inside. Therefore:
**Move at the speed of the dwarf that is guiding them. It is thus recommended to pick the most [[attribute#Agility|agile]] of your dwarves for cart-guiding tasks.
*Ignore working rollers.
*Will ''not'' collide with other guided carts even when a full frontal collision would be expected.
*Will go up ramps like nobody's business.
This is therefore the recommended method of transport for simple non-powered rail systems, despite it diverting a dwarf from other, potentially more important tasks.

Some samples with behavior:

A <-> B A <-> C A <-> B
B╥ B╥ B╥
║ ║ ║
A╞══╝ A╞══╩══╡C A╞══╬╗
You can only go A->B ╚╝
Works when the cart Works
is in Guide mode.

In the second example above, if you attempt to "Push" from B to A or C, [[Fun|''the cart will go careening off of the tracks'']].

=== Skipping ===
If a minecart is moving fast enough, it can skip over [[water]] or [[magma]], making splashes of [[mist]] (or [[magma mist]]) as it attempts to move on them horizontally. This horizontal movement is independent of the minecart and its content's [[weight]].

=== Track Jumping ===
If a minecart encounters the end of the track or a T junction where it can not continue straight it may jump off of the track if it is going fast enough. The minecart will now continue in a straight line until in encounters an obstacle, slows to a stop, or encounters another (properly aligned) Track. An escaped minecart will follow another track even if it is a corner.

=== Falling ===
When falling, a minecart appears to cause no damage upon collision with a creature, possibly to allow cart "stacking" across Z-levels. {{verify}} A dwarf riding in a minecart that is dropped multiple z-levels suffers normal fall damage. Minecarts can fall through up/down stairs.

=== Stacking ===
If a minecart lands on another minecart in exactly the perfect orientation and time, they may form a stack (effectively a pillar) of minecarts. This pillar, aside from the [[megaprojects]] uses possible, is also useful for [[trap design]] with minecarts as the weaponry.

The location of the upper minecarts, above what seems to be thin air, can be confusing. These minecarts generally need to be struck with another minecart to move out, or have their support removed. The latter option can be somewhat dangerous, however.

=== Danger ===
Minecarts are not without [[Fun|danger]]. Although designating a track automatically sets the [[traffic]] designation to low, dwarves ''may'' still walk on them, and [[creature]]s ignore traffic designations altogether. If an unlucky dwarf or creature fails to [[dodger|dodge]] a minecart, they can be injured. Most of this danger can be avoided by setting the minecart {{k|h}}auling commands to guide instead of push or ride, as dwarves guiding minecarts will ignore traffic restrictions, by [[pasture|pasturing]] domestic animals, and preventing the access of other creatures to the tracks.

Danger does not always involve living victims: careless route designation can also result in minecarts careening off tracks or colliding with each other. If this occurs, the [[item]]s may be scattered; this can cause even more hauling jobs than the minecart aimed to eliminate. Even <s>better</s> worse, scattered items, especially [[weapon]]s, can injure passing [[dwarf|dwarves]] or other [[creature]]s; in the words of Toady One the Great, "Accidental grapeshotting of the dining room should be possible now."

Of course, the danger of using minecarts means they can also be used as weapons by imaginative players.

== Automation ==

=== Track stop ===
Track stops are constructions that allow further automation of minecart systems via adjustable features such as braking by friction and automatic dumping of contents. They can be built from logs, bars and blocks through {{K|b}} {{K|C}} {{K|S}}; friction amount, dumping toggle and dumping direction must be set '''before''' construction, and these settings can be neither changed nor seen thereafter; however, track stops can be linked to [[pressure plate]]s or [[lever]]s to toggle friction upon activation. Take care not to set track stops at a loading site to dump their contents, or dwarves will never be able to fill the cart.

Track stops are not mandatory; in fact, their main use is in automated rail systems, to stop and hold extremely fast-moving minecarts or to dump contents mid-way without stopping. However, even in basic rail systems it can be useful to set a track stop to dump items: this saves time that dwarves would otherwise spend in removing items from the cart, time that is better spent driving the cart back to where it's needed.

If a stockpile is built on the square that a track stop is set to dump to, it can act as a [[ Exploit#Quantum_stockpiles|quantum stockpile]] and any items dumped from a minecart that match the storage settings of the stockpile will remain there and accumulate. Normally trackstops are built on top of existing track to operate on moving minecarts, but they can also be used without tracks to create [[Exploit#The_Minecart_Stop|automatic quantum stockpiles]] (see also [[#Example|route example]]).

Counter-intuitive to their construction method, track stops are considered [[building]]s and must be removed by {{k|q}} {{k|x}}.

=== Roller ===
A '''roller''' is a [[power]]ed [[machine component]] for the automated propulsion of minecarts. They are built with {{K|b}} {{K|M}} {{K|r}}, requiring a [[mechanic]], one or more [[mechanism]]s and a [[rope]]. Rollers are very useful to maintain a cart's momentum along long routes, to get them to climb Z-levels without dwarfpower involved, and to get them to reach speeds unattainable by guiding dwarves. These devices are variable-length, variable-direction, and variable-power, all traits that can be set at construction time; at the highest speed, a roller uses two units of power per tile it is long.

Rollers may apparently be placed directly on ramps to help pull carts up Z levels. Currently rollers can only be placed on ramps if it would result in it being connected to a preexisting power connection (gears, axles, or pumps). Rollers will transfer power along their sides but not from their front or back (the edges on the track).

Care must be taken in [[glacier]]s and other extremely cold [[biome]]s, since rollers can be rendered inoperable when exposed to freezing [[temperature]]s.

Because of their one-way nature, rollers are unsuitable for most two-way minecart tracks. However, a minecart set to be ''guided'' is not affected by rollers at all — this allows a one-way track to be used in both directions. In addition, rollers do not affect minecarts when disengaged: switching mechanisms (such as a [[pressure plate]] attached to powering [[gear assembly]]) can be used to create complex paths.

Rollers cannot be powered from above.

=== Switching ===


A rudimentary track switch can be constructed by building a T-junction as illustrated below.

B╥ B╥
║ ║
║ -> ║
║ ║
A╞════╚════╡C A╞════R════╡C

The 'R' is roller pushing from East to West.
If the cart is pushed East from the stop at 'A' while the roller is activated, it will arrive at 'B'. If the roller is not running, it will arrive at 'C'.

This switch has a disadvantage - it requires power. An alternative non-powered solution uses controlled derailment, or a connecting bridge.

B╥
║
║
A╞════╝D ════╡C

Here the track between A and C is not continuous. The only continuous track is A->B, with a corner (not a T section). Fast moving carts will tend to derail at D and rejoin the track to C. Placing a door at D will prevent the derailment, so the cart continues to B. The door is operated by mechanisms elsewhere (typically, a lever, but some fun can be had with pressure plates).

If carts are moving too slowly to reliably derail at the corner, a retractable bridge may be used as a connector between A and C.
B╥
║
║
A╞════bbb════╡C
The bridge must overlap the corner so that it acts as if a T junction track when extended. When retracted, the corner reappears, so the slower carts will continue to B.

=== Controlling Speed ===


Minecarts can reach extremely high speeds, especially when descending multiple Z-levels. A minecart will derail at a track corner if it's speed exceeds 0.5 m/s (here m/s really means tiles per step), '''unless''' the route in the direction of travel is blocked:

Will derail at > 0.5 m/s:

in ═╗->
out

Will not derail at > 0.5 m/s:

in ═╗O
|
v
out

O is wall.

This behavior can be used to build a "speed limiter", that will ensure that when a minecart exits it is traveling below derail speed:

OOOO
in ═╔═╗O
out ═╬═╝O
O╚S╝O
OOOOO

O is wall, S is a Track Stop set to High Friction or lower. If the minecart is traveling below derailment speed it will not be effected.

== Example ==

Let's construct a simple minecart route. This route will move stone blocks from an input stockpile to an output stockpile. We'll begin by creating the stockpiles:

[[File:minecart-example-1.png|Stockpiles designated.]]

The input stockpile is on the left; the output stockpile is on the right. We'll be moving blocks from left to right. Disable bins in both stockpiles, and set the input stockpile to accept only from links. Then make the stockpile take from the mason's workshop where the blocks are being produced.

Next, carve the track:

[[File:minecart-example-2.png|Track carving designation.]]

Note that the ends of the designation are uniquely shaped; this is automatic, and not anything you need to control. Now, wait for your engravers to come along and carve the track into the stone. (Your haulers will probably also fill up the input stockpile while you wait.)

In addition, while we're waiting for that to happen, we'll build an iron minecart in the forge.

[[File:minecart-example-3.png|Track carved.]]

When the track has been carved, it will look like the above (the track will be solid instead of flashing). Now, order a track stop to be constructed next to the output stockpile:

{|
| [[File:minecart-example-4.png|Track stop designation.]]
| [[File:minecart-example-5.png|Select dumping direction.]]
|}

You must press {{k|d}} three times to select the dumping direction ''before'' placing the track stop. We want our blocks to be dumped into the output stockpile east of the track stop. Then wait for a mechanic to come along and build the track stop.

[[File:minecart-example-6.png|Track stop constructed.]]

Now we'll define the actual ''route''. This is done in the {{k|h}}auling menu. Press {{k|r}} to begin defining a route. Next, move the cursor to the input end of the track, and then press {{k|s}} to define the first stop:

{|
| [[File:minecart-example-7.png|Stop 1 designation.]]
| [[File:minecart-example-8.png|Route definition, in progress.]]
|}

Move the cursor again, to the output end of the track, and press {{k|s}} again to define the second stop:

{|
| [[File:minecart-example-9.png|Stop 2 designation.]]
| [[File:minecart-example-10.png|Route definition, two stops.]]
|-
|
| [[File:minecart-example-11.png|Stops are not defined yet.]]
|}

There are several user interface features to note at this point. The stops have been positioned, but they haven't been ''defined'' yet, so there is a warning ! symbol by each of them. In the lower right corner, we see what the ! means. Also, note that the second stop is labeled in white, while the other two lines are grey. The white text is a selection indicator, and can be moved up and down by pressing {{k|+}}/{{k|-}}.

Next we need to define what our stops do. We want the minecart to be filled with blocks at the first stop, then travel to the second stop where it will dump its cargo, and then return. Press {{k|-}} to move the selection up to stop 1, and {{k|Enter}} to open it up. By default, the stop has three conditions:

[[File:minecart-example-12.png|Default stop definition.]]

We don't want any of these, so press {{k|x}} three times to delete them. This leaves us with a blank stop. Now we can add the conditions we actually want. Press {{k|n}} to begin adding the first condition, then {{k|d}} twice to change the direction from north to east. Then press {{k|c}} to change the condition from empty to full. This will instruct the minecart to be guided east when full of desired items.

To set the desired items, we create a stockpile link. Press {{k|s}}, then move the cursor to the input stockpile, then press {{k|p}} to select that stockpile. Now press {{k|Enter}}; this opens up a selection screen that resembles the stockpile customization screen. Move down to Blocks, {{k|e}}nable them, then (if you wish) restrict it to stone blocks.

When you've done all that, stop 1 should look like this:

[[File:minecart-example-13.png|Stop 1, defined.]]

Stop 2 is much simpler. All we need to do is have the minecart return to the input stop. So, make a condition and change the direction:

[[File:minecart-example-14.png|Stop 2, defined.]]

Finally, we just have to assign our minecart. Go back to the route definition screen, and press {{k|v}}. Select the minecart, and press {{k|Enter}}.

Now we've got everything set up:

[[File:minecart-example-15.png|Route, fully defined.]]

The V is red because the minecart hasn't been moved onto the track yet. Some dwarf will have to haul it from the forge to the first stop, by hand; this will take a while, especially if the forge is far away.

Once the minecart is in place, dwarves should fill it with blocks from the input stockpile, which will in turn be filled with blocks from the workshop where your mason has been toiling dutifully. When the minecart is full, the blocks will be dumped into the 1x1 stockpile on the right. Automatic quantum dumping!

== Troubleshooting ==

Because of the complexity of the system, all but the most careful and experienced minecart users will encounter issues. Most route issues can be diagnosed and fixed from the {{k|h}}auling menu.

'''Symptom:''' {{DFtext|! Set dir/connect track|6:1}} message appears to the right of one or more stops
<br>'''Possible Causes:'''
* The departure direction of the stop might be invalid. Edit the stop using {{k|Enter}} and press{{k|d}} until it is pointing in a valid direction.
* The track stop might not be built on top of a track. The track stop must be deconstructed to remedy this issue.
* Your track might not be built correctly. Make sure all connected tracks between destinations are not one-way tracks.
** This can be especially confusing with ramps. To carve a two-way track on a (natural) ramp, you must designate the ramp <b>and one square beyond</b> in the direction you want the track to go.
** Ramps '''must''' have a solid block on the side opposite to the track, or they will neither work nor be marked as "unusable". The solid block can be natural or constructed.
* The desired/kept items might not be configured correctly.

'''Symptom:''' The status '''0% <span style="color:#00dd00;">V</span>''' always appears to the right of one stop.
<br>'''Possible Causes:'''
* The stop may not be set to take from a stockpile. Edit the Stop using {{k|Enter}} and make sure you see a message like "Take from Stockpile #1".
* The take conditions must correspond with the contents of the stockpile.
* The track stop may be set to dump. A track stop set to dump cannot be filled. You must either set the stop to a time-based departure or deconstruct the track stop and rebuild it without dumping.
* Make sure the minecart itself has not been designated to be dumped (such as when using mass-dump).

== Capacity ==
Minecarts have five times the capacity of wheelbarrows, which is an enormous amount. A single minecart can carry 2500 rolls of [[cloth]], for example, or even a hundred stone blocks. Unfortunately, loading 2500 [[stone|boulder]]s onto a minecart is not possible (five boulders fit).

A glumprong minecart full with 5 pitchblende boulders weighs 3848Γ (the cart alone is 48Γ).<br />
A gold minecart full of gold bars is 10398Γ.<br />
An platinum minecart weighs 856Γ.<br />
If slade minecarts were possible, they would weigh 8000Γ empty.<br />

[[Water]] and [[magma]] can also be loaded into minecarts by submerging them to a depth of at least 6/7, and dumped by a constructed track stop. Loading fluids onto minecarts can be difficult because their weight can slow the minecart down greatly. Curiously, filling a minecart with magma does not injure a dwarf ''riding'' it. A minecart will hold enough magma to increase the depth of a single tile by 2. This amount is listed as 833 units, which weigh 999Γ. An iron or steel cart filled with magma weighs 1313Γ. An adamantine one weighs 1007Γ.

The capacity in a minecart affects whether a [[pressure plate]] triggers or not, based on the pressure plate's setting.

== Bugs ==

*If you set up lots of routes and stops and then resize your screen, the list will scroll off-screen in the hauling menu. You can still navigate the list with keyboard commands, but cannot see the stop/route name. This will be fixed in the next release.
*A dwarf will drop its [[child|baby]], if it has one, when boarding a minecart set to be ridden.
*Tracks block wagon access to trade depots.{{bug|6040}}
*Dwarves cannot guide a minecart through an unlocked door unless another dwarf opens the door{{bug|6056}}

{{Category|Fortress mode}}
{{Category|Interface}}

[[ru:Minecart]]

v0.34:Minecart

2012-09-28T04:46:58Z

Zilpin: /* Capacity */

{{quality|Fine|22:04, 14 May 2012 (UTC)}}{{av}}{{Buggy}}
A '''minecart''' is a [[tool]] used mostly for [[hauling]]. It is made of [[wood]] at a [[carpenter's workshop]], or [[metal]] at a [[metalsmith's forge]]. Minecarts store up to five times as many items as [[wheelbarrow]]s and are quite a bit faster than hauling dwarves, but have the disadvantage of requiring a dedicated track network and a complex route setup. Minecart tracks also take up a lot of space, may be complicated to construct, and can be resource-intensive.

Just like wheelbarrows, minecarts are considered [[item]]s and are stored in a [[furniture]] [[stockpile]]. Despite their five times greater capacity, they are only one third larger than wheelbarrows and are identical in base [[item value|value]] when made from the same [[material]] (the value may differ due to the [[item quality]]). As items, [[thief|thieves]] or even mischievous animals can steal minecarts, even when moving on a track. If a minecart is moving fast enough, or if it has a rider, thieves will be unable to steal the minecarts.

Although most of the utility of minecarts is in [[fortress mode]], an [[adventure mode|adventurer]] can also ride in a minecart. Adventurers can also pick up and relocate minecarts.

Since their introduction in version 0.34.08, a new [[hauling]] [[labor]] preference was added to all dwarves, called "Push/Haul Vehicles", turned on by default.

The invention of minecarts revolutionized the [[minecart logic|Science of Dwarfputing]] by enabling smaller, faster logic systems to be built.

== Track ==
Tracks can be built in two ways:
*A single-tile wide strip of natural stone can be designated to be [[Engraver|carved]] (with {{K|d}} {{k|T}}), which will create a straight two-way track. The creation of corners, crossings, and T-junctions is as simple as designating another strip of track that overlaps an existant or newly-designated track. Engraved tracks are removed by [[smoothing]] the rock they're on, which results in a smooth floor (that can be re-engraved if necessary), or by building a [[floor]] on top and subsequently removing it.
**The carving of natural ramps is a little more confusing: to carve a two-way track on a ramp (natural only, does not work on constructed ramps), you must designate the ramp '''and one square beyond''' in the direction you want the track to go. For the side of the ramp square you want to head upward, there '''must''' be either a natural or constructed wall in the square next to it, otherwise the game assumes you are trying to carve it on the same level -- this can result in the track being carved underneath a door or other object. If you have accidentally done this, you can correct it by smoothing the ramp and constructing a single square of wall next to it, then re-carving the ramp correctly. (However, the wall must stay there permanently, removing it will disconnect the track.)

*Tracks can also be built as regular [[construction]]s (through {{K|b}} {{K|C}} {{K|T}}). This method is resource-expensive, since each track tile requires one stone, [[bar]], or [[block]] for construction, and time-consuming, since you can't designate strips larger than 10 tiles at a time. Corners, crossings, T-junctions, and ramps also have to be designated individually. However, it is usually the only way to build tracks above ground (barring the [[Obsidian farming|creation of obsidian]]), and the only way to create one-way tracks. Constructed tracks are designated for removal like any regular construction; be aware that removing track ramps built on top of natural ones will also remove the original ramp, leaving a flat floor.

Every track, when complete, will designate the tile with a low-priority [[traffic|traffic order]]. This reduces the odds of dwarves walking into a high-speed minecart; however, it should be noted that pets and livestock ignore traffic orders. Note that removing the track doesn't reset that tile back to normal traffic priority, so you may wish to manually clean up traffic designation afterward. Also note that bridges that are used as tracks don't have their traffic priority changed automatically (since they're just normal bridges), which could cause dwarves to pathfind normally through dangerous minecart entrances in your fort's walls if you're not careful.

As constructions or tile features, [[door]]s and other furniture can be built on tracks. A [[door]] or [[floodgate]] can be turned on or off by a [[lever]], effectively controlling the flow of automated minecarts. This may be dangerous, however. 

[[Bridge]]s can also act as tracks, but only if they're lowered or not retracted. This property can enable levers to turn tracks on and off. However, care should be taken to ensure that such bridges are never operated while a cart is on top of them, as the cart will be flung off the track. It's worth noting that it's often faster, and cheaper, to construct large bridges than long sections of constructed track. It's also worth noting that bridges do not automatically have a low pathfinding traffic priority assigned to them, however.

== Hauling route ==
The proper setting up of routes is essential for a working rail system. Routes, stops, departure conditions and stockpile links are managed from the {{k|h}}auling menu.

=== Route ===
New routes are created with the {{k|h}}auling key. Existing ones can be removed (without confirmation) with the {{k|x}} key, and also {{k|n}}icknamed. Before operating, the route must have at least one {{k|v}}ehicle assigned to it (this can be done with either the route or a stop selected). Assigning a full minecart to a route may result in a slow hauling job if the contents are heavy.

=== Stop ===
Stops are designated by moving the cursor on top of the desired tile and pressing the {{k|s}} key afterwards. They can be removed with and nicknamed with the same hotkeys as routes. Stops can also be reordered with the {{k|p}}romote key. Without a definition, however, a stop is fairly useless: pressing the {{k|Enter}} key with a stop selected in the route menu opens its stop definition screen, from which departure conditions and stockpile links can be set up.

==== Stockpile links ====
By placing the cursor on top of a stockpile and using {{k|s}}, you can create stockpile links for a track stop. Links can also be redefined by selecting them, placing the cursor over a different stockpile, and pressing {{k|p}}.

==== Departure condition ====
Departure conditions involve setting conditions in which the minecart will leave on the route. Each condition includes:
# A departure mode (Guide, Ride or Push).
# A departure direction (NSEW).
# A timer, before which the departure condition cannot be met.
# Conditions on the amount of items in the cart.
Departure conditions are created with the {{k|n}} key. A new departure condition will read: "guide north immediately when empty of desired items". This condition can be changed between basic presets with {{k|c}}. "Advanced" mode ({{k|C}}) allows for more precise control over departure conditions: fine tuning the percentage from 0 to 100 in 25% steps ({{k|f}} and {{k|F}}), switching it being either the maximum or the minimum amount of items for the condition to be met ({{k|m}}), and whether the cart accepts all or only a specific set of items ({{k|l}}). Common to both screens are the departure mode ({{k|p}}, Push, Ride or Guide), {{k|d}}irection, and timer ({{k|t}} and {{k|T}}) options.

To have a cart only carry a specific set of items, the stop can be set to only carry "desired" items, opening the selection screen with the {{k|Enter}} key while having said stop condition selected, and toggling as desired, or it can simply be linked to a restricted stockpile and set to depart with any items.

== Physics ==


Minecart physics depend greatly on the departure mode set in the route stop conditions.

When set to "Push" or "Ride", minecarts will move according to the regular laws of momentum, gaining speed when going downhill, losing it slowly due to friction when on a flat plane, and more quickly when going uphill. In these modes, minecarts will move along the track in a straight line until they either run off the tracks or encounter a turn. A minecart will continue straight at a T junction if possible but if it is not possible the track is treated as a dead end and may jump track. The cart's behavior also depends on the weight of its contents (including fluids and dwarves): heavily loaded carts are harder to accelerate and to stop, and gain more momentum when going downhill. In either case, dwarves can not push nor ride an unpowered cart up a ramp, bouncing back the direction it came. At best, this is a waste of time; at worst, it will give your cart-pushing dwarf a [[fun|fun surprise]]. To solve this, the player can either use Rollers (see below) or set the cart to be Guided.

When set to "Guide", minecarts seem to ignore all laws of physics. They:
*Ignore the weight of any and all items inside. Therefore:
**Move at the speed of the dwarf that is guiding them. It is thus recommended to pick the most [[attribute#Agility|agile]] of your dwarves for cart-guiding tasks.
*Ignore working rollers.
*Will ''not'' collide with other guided carts even when a full frontal collision would be expected.
*Will go up ramps like nobody's business.
This is therefore the recommended method of transport for simple non-powered rail systems, despite it diverting a dwarf from other, potentially more important tasks.

Some samples with behavior:

A <-> B A <-> C A <-> B
B╥ B╥ B╥
║ ║ ║
A╞══╝ A╞══╩══╡C A╞══╬╗
You can only go A->B ╚╝
Works when the cart Works
is in Guide mode.

In the second example above, if you attempt to "Push" from B to A or C, [[Fun|''the cart will go careening off of the tracks'']].

=== Skipping ===
If a minecart is moving fast enough, it can skip over [[water]] or [[magma]], making splashes of [[mist]] (or [[magma mist]]) as it attempts to move on them horizontally. This horizontal movement is independent of the minecart and its content's [[weight]].

=== Track Jumping ===
If a minecart encounters the end of the track or a T junction where it can not continue straight it may jump off of the track if it is going fast enough. The minecart will now continue in a straight line until in encounters an obstacle, slows to a stop, or encounters another (properly aligned) Track. An escaped minecart will follow another track even if it is a corner.

=== Falling ===
When falling, a minecart appears to cause no damage upon collision with a creature, possibly to allow cart "stacking" across Z-levels. {{verify}} A dwarf riding in a minecart that is dropped multiple z-levels suffers normal fall damage. Minecarts can fall through up/down stairs.

=== Stacking ===
If a minecart lands on another minecart in exactly the perfect orientation and time, they may form a stack (effectively a pillar) of minecarts. This pillar, aside from the [[megaprojects]] uses possible, is also useful for [[trap design]] with minecarts as the weaponry.

The location of the upper minecarts, above what seems to be thin air, can be confusing. These minecarts generally need to be struck with another minecart to move out, or have their support removed. The latter option can be somewhat dangerous, however.

=== Danger ===
Minecarts are not without [[Fun|danger]]. Although designating a track automatically sets the [[traffic]] designation to low, dwarves ''may'' still walk on them, and [[creature]]s ignore traffic designations altogether. If an unlucky dwarf or creature fails to [[dodger|dodge]] a minecart, they can be injured. Most of this danger can be avoided by setting the minecart {{k|h}}auling commands to guide instead of push or ride, as dwarves guiding minecarts will ignore traffic restrictions, by [[pasture|pasturing]] domestic animals, and preventing the access of other creatures to the tracks.

Danger does not always involve living victims: careless route designation can also result in minecarts careening off tracks or colliding with each other. If this occurs, the [[item]]s may be scattered; this can cause even more hauling jobs than the minecart aimed to eliminate. Even <s>better</s> worse, scattered items, especially [[weapon]]s, can injure passing [[dwarf|dwarves]] or other [[creature]]s; in the words of Toady One the Great, "Accidental grapeshotting of the dining room should be possible now."

Of course, the danger of using minecarts means they can also be used as weapons by imaginative players.

== Automation ==

=== Track stop ===
Track stops are constructions that allow further automation of minecart systems via adjustable features such as braking by friction and automatic dumping of contents. They can be built from logs, bars and blocks through {{K|b}} {{K|C}} {{K|S}}; friction amount, dumping toggle and dumping direction must be set '''before''' construction, and these settings can be neither changed nor seen thereafter; however, track stops can be linked to [[pressure plate]]s or [[lever]]s to toggle friction upon activation. Take care not to set track stops at a loading site to dump their contents, or dwarves will never be able to fill the cart.

Track stops are not mandatory; in fact, their main use is in automated rail systems, to stop and hold extremely fast-moving minecarts or to dump contents mid-way without stopping. However, even in basic rail systems it can be useful to set a track stop to dump items: this saves time that dwarves would otherwise spend in removing items from the cart, time that is better spent driving the cart back to where it's needed.

If a stockpile is built on the square that a track stop is set to dump to, it can act as a [[ Exploit#Quantum_stockpiles|quantum stockpile]] and any items dumped from a minecart that match the storage settings of the stockpile will remain there and accumulate. Normally trackstops are built on top of existing track to operate on moving minecarts, but they can also be used without tracks to create [[Exploit#The_Minecart_Stop|automatic quantum stockpiles]] (see also [[#Example|route example]]).

Counter-intuitive to their construction method, track stops are considered [[building]]s and must be removed by {{k|q}} {{k|x}}.

=== Roller ===
A '''roller''' is a [[power]]ed [[machine component]] for the automated propulsion of minecarts. They are built with {{K|b}} {{K|M}} {{K|r}}, requiring a [[mechanic]], one or more [[mechanism]]s and a [[rope]]. Rollers are very useful to maintain a cart's momentum along long routes, to get them to climb Z-levels without dwarfpower involved, and to get them to reach speeds unattainable by guiding dwarves. These devices are variable-length, variable-direction, and variable-power, all traits that can be set at construction time; at the highest speed, a roller uses two units of power per tile it is long.

Rollers may apparently be placed directly on ramps to help pull carts up Z levels. Currently rollers can only be placed on ramps if it would result in it being connected to a preexisting power connection (gears, axles, or pumps). Rollers will transfer power along their sides but not from their front or back (the edges on the track).

Care must be taken in [[glacier]]s and other extremely cold [[biome]]s, since rollers can be rendered inoperable when exposed to freezing [[temperature]]s.

Because of their one-way nature, rollers are unsuitable for most two-way minecart tracks. However, a minecart set to be ''guided'' is not affected by rollers at all — this allows a one-way track to be used in both directions. In addition, rollers do not affect minecarts when disengaged: switching mechanisms (such as a [[pressure plate]] attached to powering [[gear assembly]]) can be used to create complex paths.

Rollers cannot be powered from above.

=== Switching ===


A rudimentary track switch can be constructed by building a T-junction as illustrated below.

B╥ B╥
║ ║
║ -> ║
║ ║
A╞════╚════╡C A╞════R════╡C

The 'R' is roller pushing from East to West.
If the cart is pushed East from the stop at 'A' while the roller is activated, it will arrive at 'B'. If the roller is not running, it will arrive at 'C'.

This switch has a disadvantage - it requires power. An alternative non-powered solution uses controlled derailment, or a connecting bridge.

B╥
║
║
A╞════╝D ════╡C

Here the track between A and C is not continuous. The only continuous track is A->B, with a corner (not a T section). Fast moving carts will tend to derail at D and rejoin the track to C. Placing a door at D will prevent the derailment, so the cart continues to B. The door is operated by mechanisms elsewhere (typically, a lever, but some fun can be had with pressure plates).

If carts are moving too slowly to reliably derail at the corner, a retractable bridge may be used as a connector between A and C.
B╥
║
║
A╞════bbb════╡C
The bridge must overlap the corner so that it acts as if a T junction track when extended. When retracted, the corner reappears, so the slower carts will continue to B.

=== Controlling Speed ===


Minecarts can reach extremely high speeds, especially when descending multiple Z-levels. A minecart will derail at a track corner if it's speed exceeds 0.5 m/s (here m/s really means tiles per step), '''unless''' the route in the direction of travel is blocked:

Will derail at > 0.5 m/s:

in ═╗->
out

Will not derail at > 0.5 m/s:

in ═╗O
|
v
out

O is wall.

This behavior can be used to build a "speed limiter", that will ensure that when a minecart exits it is traveling below derail speed:

OOOO
in ═╔═╗O
out ═╬═╝O
O╚S╝O
OOOOO

O is wall, S is a Track Stop set to High Friction or lower. If the minecart is traveling below derailment speed it will not be effected.

== Example ==

Let's construct a simple minecart route. This route will move stone blocks from an input stockpile to an output stockpile. We'll begin by creating the stockpiles:

[[File:minecart-example-1.png|Stockpiles designated.]]

The input stockpile is on the left; the output stockpile is on the right. We'll be moving blocks from left to right. Disable bins in both stockpiles, and set the input stockpile to accept only from links. Then make the stockpile take from the mason's workshop where the blocks are being produced.

Next, carve the track:

[[File:minecart-example-2.png|Track carving designation.]]

Note that the ends of the designation are uniquely shaped; this is automatic, and not anything you need to control. Now, wait for your engravers to come along and carve the track into the stone. (Your haulers will probably also fill up the input stockpile while you wait.)

In addition, while we're waiting for that to happen, we'll build an iron minecart in the forge.

[[File:minecart-example-3.png|Track carved.]]

When the track has been carved, it will look like the above (the track will be solid instead of flashing). Now, order a track stop to be constructed next to the output stockpile:

{|
| [[File:minecart-example-4.png|Track stop designation.]]
| [[File:minecart-example-5.png|Select dumping direction.]]
|}

You must press {{k|d}} three times to select the dumping direction ''before'' placing the track stop. We want our blocks to be dumped into the output stockpile east of the track stop. Then wait for a mechanic to come along and build the track stop.

[[File:minecart-example-6.png|Track stop constructed.]]

Now we'll define the actual ''route''. This is done in the {{k|h}}auling menu. Press {{k|r}} to begin defining a route. Next, move the cursor to the input end of the track, and then press {{k|s}} to define the first stop:

{|
| [[File:minecart-example-7.png|Stop 1 designation.]]
| [[File:minecart-example-8.png|Route definition, in progress.]]
|}

Move the cursor again, to the output end of the track, and press {{k|s}} again to define the second stop:

{|
| [[File:minecart-example-9.png|Stop 2 designation.]]
| [[File:minecart-example-10.png|Route definition, two stops.]]
|-
|
| [[File:minecart-example-11.png|Stops are not defined yet.]]
|}

There are several user interface features to note at this point. The stops have been positioned, but they haven't been ''defined'' yet, so there is a warning ! symbol by each of them. In the lower right corner, we see what the ! means. Also, note that the second stop is labeled in white, while the other two lines are grey. The white text is a selection indicator, and can be moved up and down by pressing {{k|+}}/{{k|-}}.

Next we need to define what our stops do. We want the minecart to be filled with blocks at the first stop, then travel to the second stop where it will dump its cargo, and then return. Press {{k|-}} to move the selection up to stop 1, and {{k|Enter}} to open it up. By default, the stop has three conditions:

[[File:minecart-example-12.png|Default stop definition.]]

We don't want any of these, so press {{k|x}} three times to delete them. This leaves us with a blank stop. Now we can add the conditions we actually want. Press {{k|n}} to begin adding the first condition, then {{k|d}} twice to change the direction from north to east. Then press {{k|c}} to change the condition from empty to full. This will instruct the minecart to be guided east when full of desired items.

To set the desired items, we create a stockpile link. Press {{k|s}}, then move the cursor to the input stockpile, then press {{k|p}} to select that stockpile. Now press {{k|Enter}}; this opens up a selection screen that resembles the stockpile customization screen. Move down to Blocks, {{k|e}}nable them, then (if you wish) restrict it to stone blocks.

When you've done all that, stop 1 should look like this:

[[File:minecart-example-13.png|Stop 1, defined.]]

Stop 2 is much simpler. All we need to do is have the minecart return to the input stop. So, make a condition and change the direction:

[[File:minecart-example-14.png|Stop 2, defined.]]

Finally, we just have to assign our minecart. Go back to the route definition screen, and press {{k|v}}. Select the minecart, and press {{k|Enter}}.

Now we've got everything set up:

[[File:minecart-example-15.png|Route, fully defined.]]

The V is red because the minecart hasn't been moved onto the track yet. Some dwarf will have to haul it from the forge to the first stop, by hand; this will take a while, especially if the forge is far away.

Once the minecart is in place, dwarves should fill it with blocks from the input stockpile, which will in turn be filled with blocks from the workshop where your mason has been toiling dutifully. When the minecart is full, the blocks will be dumped into the 1x1 stockpile on the right. Automatic quantum dumping!

== Troubleshooting ==

Because of the complexity of the system, all but the most careful and experienced minecart users will encounter issues. Most route issues can be diagnosed and fixed from the {{k|h}}auling menu.

'''Symptom:''' {{DFtext|! Set dir/connect track|6:1}} message appears to the right of one or more stops
<br>'''Possible Causes:'''
* The departure direction of the stop might be invalid. Edit the stop using {{k|Enter}} and press{{k|d}} until it is pointing in a valid direction.
* The track stop might not be built on top of a track. The track stop must be deconstructed to remedy this issue.
* Your track might not be built correctly. Make sure all connected tracks between destinations are not one-way tracks.
** This can be especially confusing with ramps. To carve a two-way track on a (natural) ramp, you must designate the ramp <b>and one square beyond</b> in the direction you want the track to go.
** Ramps '''must''' have a solid block on the side opposite to the track, or they will neither work nor be marked as "unusable". The solid block can be natural or constructed.
* The desired/kept items might not be configured correctly.

'''Symptom:''' The status '''0% <span style="color:#00dd00;">V</span>''' always appears to the right of one stop.
<br>'''Possible Causes:'''
* The stop may not be set to take from a stockpile. Edit the Stop using {{k|Enter}} and make sure you see a message like "Take from Stockpile #1".
* The take conditions must correspond with the contents of the stockpile.
* The track stop may be set to dump. A track stop set to dump cannot be filled. You must either set the stop to a time-based departure or deconstruct the track stop and rebuild it without dumping.
* Make sure the minecart itself has not been designated to be dumped (such as when using mass-dump).

== Capacity ==
Minecarts have five times the capacity of wheelbarrows, which is an enormous amount. A single minecart can carry 2500 rolls of [[cloth]], for example, or even a hundred stone blocks. Unfortunately, loading 2500 [[stone|boulder]]s onto a minecart is not possible (five boulders fit).

A glumprong minecart full with 5 pitchblende boulders weighs 3848Γ (the cart alone is 48Γ).
A gold minecart full of gold bars is 10398Γ.

[[Water]] and [[magma]] can also be loaded into minecarts by submerging them to a depth of at least 6/7, and dumped by a constructed track stop. Loading fluids onto minecarts can be difficult because their weight can slow the minecart down greatly. Curiously, filling a minecart with magma does not injure a dwarf ''riding'' it. A minecart will hold enough magma to increase the depth of a single tile by 2. This amount is listed as 833 units, which weigh 999Γ. An iron or steel cart filled with magma weighs 1313Γ. An adamantine one weighs 1007Γ.

The capacity in a minecart affects whether a [[pressure plate]] triggers or not, based on the pressure plate's setting.

== Bugs ==

*If you set up lots of routes and stops and then resize your screen, the list will scroll off-screen in the hauling menu. You can still navigate the list with keyboard commands, but cannot see the stop/route name. This will be fixed in the next release.
*A dwarf will drop its [[child|baby]], if it has one, when boarding a minecart set to be ridden.
*Tracks block wagon access to trade depots.{{bug|6040}}
*Dwarves cannot guide a minecart through an unlocked door unless another dwarf opens the door{{bug|6056}}

{{Category|Fortress mode}}
{{Category|Interface}}

[[ru:Minecart]]

v0.34:Minecart

2012-09-28T02:05:43Z

Zilpin: /* Capacity */

{{quality|Fine|22:04, 14 May 2012 (UTC)}}{{av}}{{Buggy}}
A '''minecart''' is a [[tool]] used mostly for [[hauling]]. It is made of [[wood]] at a [[carpenter's workshop]], or [[metal]] at a [[metalsmith's forge]]. Minecarts store up to five times as many items as [[wheelbarrow]]s and are quite a bit faster than hauling dwarves, but have the disadvantage of requiring a dedicated track network and a complex route setup. Minecart tracks also take up a lot of space, may be complicated to construct, and can be resource-intensive.

Just like wheelbarrows, minecarts are considered [[item]]s and are stored in a [[furniture]] [[stockpile]]. Despite their five times greater capacity, they are only one third larger than wheelbarrows and are identical in base [[item value|value]] when made from the same [[material]] (the value may differ due to the [[item quality]]). As items, [[thief|thieves]] or even mischievous animals can steal minecarts, even when moving on a track. If a minecart is moving fast enough, or if it has a rider, thieves will be unable to steal the minecarts.

Although most of the utility of minecarts is in [[fortress mode]], an [[adventure mode|adventurer]] can also ride in a minecart. Adventurers can also pick up and relocate minecarts.

Since their introduction in version 0.34.08, a new [[hauling]] [[labor]] preference was added to all dwarves, called "Push/Haul Vehicles", turned on by default.

The invention of minecarts revolutionized the [[minecart logic|Science of Dwarfputing]] by enabling smaller, faster logic systems to be built.

== Track ==
Tracks can be built in two ways:
*A single-tile wide strip of natural stone can be designated to be [[Engraver|carved]] (with {{K|d}} {{k|T}}), which will create a straight two-way track. The creation of corners, crossings, and T-junctions is as simple as designating another strip of track that overlaps an existant or newly-designated track. Engraved tracks are removed by [[smoothing]] the rock they're on, which results in a smooth floor (that can be re-engraved if necessary), or by building a [[floor]] on top and subsequently removing it.
**The carving of natural ramps is a little more confusing: to carve a two-way track on a ramp (natural only, does not work on constructed ramps), you must designate the ramp '''and one square beyond''' in the direction you want the track to go. For the side of the ramp square you want to head upward, there '''must''' be either a natural or constructed wall in the square next to it, otherwise the game assumes you are trying to carve it on the same level -- this can result in the track being carved underneath a door or other object. If you have accidentally done this, you can correct it by smoothing the ramp and constructing a single square of wall next to it, then re-carving the ramp correctly. (However, the wall must stay there permanently, removing it will disconnect the track.)

*Tracks can also be built as regular [[construction]]s (through {{K|b}} {{K|C}} {{K|T}}). This method is resource-expensive, since each track tile requires one stone, [[bar]], or [[block]] for construction, and time-consuming, since you can't designate strips larger than 10 tiles at a time. Corners, crossings, T-junctions, and ramps also have to be designated individually. However, it is usually the only way to build tracks above ground (barring the [[Obsidian farming|creation of obsidian]]), and the only way to create one-way tracks. Constructed tracks are designated for removal like any regular construction; be aware that removing track ramps built on top of natural ones will also remove the original ramp, leaving a flat floor.

Every track, when complete, will designate the tile with a low-priority [[traffic|traffic order]]. This reduces the odds of dwarves walking into a high-speed minecart; however, it should be noted that pets and livestock ignore traffic orders. Note that removing the track doesn't reset that tile back to normal traffic priority, so you may wish to manually clean up traffic designation afterward. Also note that bridges that are used as tracks don't have their traffic priority changed automatically (since they're just normal bridges), which could cause dwarves to pathfind normally through dangerous minecart entrances in your fort's walls if you're not careful.

As constructions or tile features, [[door]]s and other furniture can be built on tracks. A [[door]] or [[floodgate]] can be turned on or off by a [[lever]], effectively controlling the flow of automated minecarts. This may be dangerous, however. 

[[Bridge]]s can also act as tracks, but only if they're lowered or not retracted. This property can enable levers to turn tracks on and off. However, care should be taken to ensure that such bridges are never operated while a cart is on top of them, as the cart will be flung off the track. It's worth noting that it's often faster, and cheaper, to construct large bridges than long sections of constructed track. It's also worth noting that bridges do not automatically have a low pathfinding traffic priority assigned to them, however.

== Hauling route ==
The proper setting up of routes is essential for a working rail system. Routes, stops, departure conditions and stockpile links are managed from the {{k|h}}auling menu.

=== Route ===
New routes are created with the {{k|h}}auling key. Existing ones can be removed (without confirmation) with the {{k|x}} key, and also {{k|n}}icknamed. Before operating, the route must have at least one {{k|v}}ehicle assigned to it (this can be done with either the route or a stop selected). Assigning a full minecart to a route may result in a slow hauling job if the contents are heavy.

=== Stop ===
Stops are designated by moving the cursor on top of the desired tile and pressing the {{k|s}} key afterwards. They can be removed with and nicknamed with the same hotkeys as routes. Stops can also be reordered with the {{k|p}}romote key. Without a definition, however, a stop is fairly useless: pressing the {{k|Enter}} key with a stop selected in the route menu opens its stop definition screen, from which departure conditions and stockpile links can be set up.

==== Stockpile links ====
By placing the cursor on top of a stockpile and using {{k|s}}, you can create stockpile links for a track stop. Links can also be redefined by selecting them, placing the cursor over a different stockpile, and pressing {{k|p}}.

==== Departure condition ====
Departure conditions involve setting conditions in which the minecart will leave on the route. Each condition includes:
# A departure mode (Guide, Ride or Push).
# A departure direction (NSEW).
# A timer, before which the departure condition cannot be met.
# Conditions on the amount of items in the cart.
Departure conditions are created with the {{k|n}} key. A new departure condition will read: "guide north immediately when empty of desired items". This condition can be changed between basic presets with {{k|c}}. "Advanced" mode ({{k|C}}) allows for more precise control over departure conditions: fine tuning the percentage from 0 to 100 in 25% steps ({{k|f}} and {{k|F}}), switching it being either the maximum or the minimum amount of items for the condition to be met ({{k|m}}), and whether the cart accepts all or only a specific set of items ({{k|l}}). Common to both screens are the departure mode ({{k|p}}, Push, Ride or Guide), {{k|d}}irection, and timer ({{k|t}} and {{k|T}}) options.

To have a cart only carry a specific set of items, the stop can be set to only carry "desired" items, opening the selection screen with the {{k|Enter}} key while having said stop condition selected, and toggling as desired, or it can simply be linked to a restricted stockpile and set to depart with any items.

== Physics ==


Minecart physics depend greatly on the departure mode set in the route stop conditions.

When set to "Push" or "Ride", minecarts will move according to the regular laws of momentum, gaining speed when going downhill, losing it slowly due to friction when on a flat plane, and more quickly when going uphill. In these modes, minecarts will move along the track in a straight line until they either run off the tracks or encounter a turn. A minecart will continue straight at a T junction if possible but if it is not possible the track is treated as a dead end and may jump track. The cart's behavior also depends on the weight of its contents (including fluids and dwarves): heavily loaded carts are harder to accelerate and to stop, and gain more momentum when going downhill. In either case, dwarves can not push nor ride an unpowered cart up a ramp, bouncing back the direction it came. At best, this is a waste of time; at worst, it will give your cart-pushing dwarf a [[fun|fun surprise]]. To solve this, the player can either use Rollers (see below) or set the cart to be Guided.

When set to "Guide", minecarts seem to ignore all laws of physics. They:
*Ignore the weight of any and all items inside. Therefore:
**Move at the speed of the dwarf that is guiding them. It is thus recommended to pick the most [[attribute#Agility|agile]] of your dwarves for cart-guiding tasks.
*Ignore working rollers.
*Will ''not'' collide with other guided carts even when a full frontal collision would be expected.
*Will go up ramps like nobody's business.
This is therefore the recommended method of transport for simple non-powered rail systems, despite it diverting a dwarf from other, potentially more important tasks.

Some samples with behavior:

A <-> B A <-> C A <-> B
B╥ B╥ B╥
║ ║ ║
A╞══╝ A╞══╩══╡C A╞══╬╗
You can only go A->B ╚╝
Works when the cart Works
is in Guide mode.

In the second example above, if you attempt to "Push" from B to A or C, [[Fun|''the cart will go careening off of the tracks'']].

=== Skipping ===
If a minecart is moving fast enough, it can skip over [[water]] or [[magma]], making splashes of [[mist]] (or [[magma mist]]) as it attempts to move on them horizontally. This horizontal movement is independent of the minecart and its content's [[weight]].

=== Track Jumping ===
If a minecart encounters the end of the track or a T junction where it can not continue straight it may jump off of the track if it is going fast enough. The minecart will now continue in a straight line until in encounters an obstacle, slows to a stop, or encounters another (properly aligned) Track. An escaped minecart will follow another track even if it is a corner.

=== Falling ===
When falling, a minecart appears to cause no damage upon collision with a creature, possibly to allow cart "stacking" across Z-levels. {{verify}} A dwarf riding in a minecart that is dropped multiple z-levels suffers normal fall damage. Minecarts can fall through up/down stairs.

=== Stacking ===
If a minecart lands on another minecart in exactly the perfect orientation and time, they may form a stack (effectively a pillar) of minecarts. This pillar, aside from the [[megaprojects]] uses possible, is also useful for [[trap design]] with minecarts as the weaponry.

The location of the upper minecarts, above what seems to be thin air, can be confusing. These minecarts generally need to be struck with another minecart to move out, or have their support removed. The latter option can be somewhat dangerous, however.

=== Danger ===
Minecarts are not without [[Fun|danger]]. Although designating a track automatically sets the [[traffic]] designation to low, dwarves ''may'' still walk on them, and [[creature]]s ignore traffic designations altogether. If an unlucky dwarf or creature fails to [[dodger|dodge]] a minecart, they can be injured. Most of this danger can be avoided by setting the minecart {{k|h}}auling commands to guide instead of push or ride, as dwarves guiding minecarts will ignore traffic restrictions, by [[pasture|pasturing]] domestic animals, and preventing the access of other creatures to the tracks.

Danger does not always involve living victims: careless route designation can also result in minecarts careening off tracks or colliding with each other. If this occurs, the [[item]]s may be scattered; this can cause even more hauling jobs than the minecart aimed to eliminate. Even <s>better</s> worse, scattered items, especially [[weapon]]s, can injure passing [[dwarf|dwarves]] or other [[creature]]s; in the words of Toady One the Great, "Accidental grapeshotting of the dining room should be possible now."

Of course, the danger of using minecarts means they can also be used as weapons by imaginative players.

== Automation ==

=== Track stop ===
Track stops are constructions that allow further automation of minecart systems via adjustable features such as braking by friction and automatic dumping of contents. They can be built from logs, bars and blocks through {{K|b}} {{K|C}} {{K|S}}; friction amount, dumping toggle and dumping direction must be set '''before''' construction, and these settings can be neither changed nor seen thereafter; however, track stops can be linked to [[pressure plate]]s or [[lever]]s to toggle friction upon activation. Take care not to set track stops at a loading site to dump their contents, or dwarves will never be able to fill the cart.

Track stops are not mandatory; in fact, their main use is in automated rail systems, to stop and hold extremely fast-moving minecarts or to dump contents mid-way without stopping. However, even in basic rail systems it can be useful to set a track stop to dump items: this saves time that dwarves would otherwise spend in removing items from the cart, time that is better spent driving the cart back to where it's needed.

If a stockpile is built on the square that a track stop is set to dump to, it can act as a [[ Exploit#Quantum_stockpiles|quantum stockpile]] and any items dumped from a minecart that match the storage settings of the stockpile will remain there and accumulate. Normally trackstops are built on top of existing track to operate on moving minecarts, but they can also be used without tracks to create [[Exploit#The_Minecart_Stop|automatic quantum stockpiles]] (see also [[#Example|route example]]).

Counter-intuitive to their construction method, track stops are considered [[building]]s and must be removed by {{k|q}} {{k|x}}.

=== Roller ===
A '''roller''' is a [[power]]ed [[machine component]] for the automated propulsion of minecarts. They are built with {{K|b}} {{K|M}} {{K|r}}, requiring a [[mechanic]], one or more [[mechanism]]s and a [[rope]]. Rollers are very useful to maintain a cart's momentum along long routes, to get them to climb Z-levels without dwarfpower involved, and to get them to reach speeds unattainable by guiding dwarves. These devices are variable-length, variable-direction, and variable-power, all traits that can be set at construction time; at the highest speed, a roller uses two units of power per tile it is long.

Rollers may apparently be placed directly on ramps to help pull carts up Z levels. Currently rollers can only be placed on ramps if it would result in it being connected to a preexisting power connection (gears, axles, or pumps). Rollers will transfer power along their sides but not from their front or back (the edges on the track).

Care must be taken in [[glacier]]s and other extremely cold [[biome]]s, since rollers can be rendered inoperable when exposed to freezing [[temperature]]s.

Because of their one-way nature, rollers are unsuitable for most two-way minecart tracks. However, a minecart set to be ''guided'' is not affected by rollers at all — this allows a one-way track to be used in both directions. In addition, rollers do not affect minecarts when disengaged: switching mechanisms (such as a [[pressure plate]] attached to powering [[gear assembly]]) can be used to create complex paths.

Rollers cannot be powered from above.

=== Switching ===


A rudimentary track switch can be constructed by building a T-junction as illustrated below.

B╥ B╥
║ ║
║ -> ║
║ ║
A╞════╚════╡C A╞════R════╡C

The 'R' is roller pushing from East to West.
If the cart is pushed East from the stop at 'A' while the roller is activated, it will arrive at 'B'. If the roller is not running, it will arrive at 'C'.

This switch has a disadvantage - it requires power. An alternative non-powered solution uses controlled derailment, or a connecting bridge.

B╥
║
║
A╞════╝D ════╡C

Here the track between A and C is not continuous. The only continuous track is A->B, with a corner (not a T section). Fast moving carts will tend to derail at D and rejoin the track to C. Placing a door at D will prevent the derailment, so the cart continues to B. The door is operated by mechanisms elsewhere (typically, a lever, but some fun can be had with pressure plates).

If carts are moving too slowly to reliably derail at the corner, a retractable bridge may be used as a connector between A and C.
B╥
║
║
A╞════bbb════╡C
The bridge must overlap the corner so that it acts as if a T junction track when extended. When retracted, the corner reappears, so the slower carts will continue to B.

=== Controlling Speed ===


Minecarts can reach extremely high speeds, especially when descending multiple Z-levels. A minecart will derail at a track corner if it's speed exceeds 0.5 m/s (here m/s really means tiles per step), '''unless''' the route in the direction of travel is blocked:

Will derail at > 0.5 m/s:

in ═╗->
out

Will not derail at > 0.5 m/s:

in ═╗O
|
v
out

O is wall.

This behavior can be used to build a "speed limiter", that will ensure that when a minecart exits it is traveling below derail speed:

OOOO
in ═╔═╗O
out ═╬═╝O
O╚S╝O
OOOOO

O is wall, S is a Track Stop set to High Friction or lower. If the minecart is traveling below derailment speed it will not be effected.

== Example ==

Let's construct a simple minecart route. This route will move stone blocks from an input stockpile to an output stockpile. We'll begin by creating the stockpiles:

[[File:minecart-example-1.png|Stockpiles designated.]]

The input stockpile is on the left; the output stockpile is on the right. We'll be moving blocks from left to right. Disable bins in both stockpiles, and set the input stockpile to accept only from links. Then make the stockpile take from the mason's workshop where the blocks are being produced.

Next, carve the track:

[[File:minecart-example-2.png|Track carving designation.]]

Note that the ends of the designation are uniquely shaped; this is automatic, and not anything you need to control. Now, wait for your engravers to come along and carve the track into the stone. (Your haulers will probably also fill up the input stockpile while you wait.)

In addition, while we're waiting for that to happen, we'll build an iron minecart in the forge.

[[File:minecart-example-3.png|Track carved.]]

When the track has been carved, it will look like the above (the track will be solid instead of flashing). Now, order a track stop to be constructed next to the output stockpile:

{|
| [[File:minecart-example-4.png|Track stop designation.]]
| [[File:minecart-example-5.png|Select dumping direction.]]
|}

You must press {{k|d}} three times to select the dumping direction ''before'' placing the track stop. We want our blocks to be dumped into the output stockpile east of the track stop. Then wait for a mechanic to come along and build the track stop.

[[File:minecart-example-6.png|Track stop constructed.]]

Now we'll define the actual ''route''. This is done in the {{k|h}}auling menu. Press {{k|r}} to begin defining a route. Next, move the cursor to the input end of the track, and then press {{k|s}} to define the first stop:

{|
| [[File:minecart-example-7.png|Stop 1 designation.]]
| [[File:minecart-example-8.png|Route definition, in progress.]]
|}

Move the cursor again, to the output end of the track, and press {{k|s}} again to define the second stop:

{|
| [[File:minecart-example-9.png|Stop 2 designation.]]
| [[File:minecart-example-10.png|Route definition, two stops.]]
|-
|
| [[File:minecart-example-11.png|Stops are not defined yet.]]
|}

There are several user interface features to note at this point. The stops have been positioned, but they haven't been ''defined'' yet, so there is a warning ! symbol by each of them. In the lower right corner, we see what the ! means. Also, note that the second stop is labeled in white, while the other two lines are grey. The white text is a selection indicator, and can be moved up and down by pressing {{k|+}}/{{k|-}}.

Next we need to define what our stops do. We want the minecart to be filled with blocks at the first stop, then travel to the second stop where it will dump its cargo, and then return. Press {{k|-}} to move the selection up to stop 1, and {{k|Enter}} to open it up. By default, the stop has three conditions:

[[File:minecart-example-12.png|Default stop definition.]]

We don't want any of these, so press {{k|x}} three times to delete them. This leaves us with a blank stop. Now we can add the conditions we actually want. Press {{k|n}} to begin adding the first condition, then {{k|d}} twice to change the direction from north to east. Then press {{k|c}} to change the condition from empty to full. This will instruct the minecart to be guided east when full of desired items.

To set the desired items, we create a stockpile link. Press {{k|s}}, then move the cursor to the input stockpile, then press {{k|p}} to select that stockpile. Now press {{k|Enter}}; this opens up a selection screen that resembles the stockpile customization screen. Move down to Blocks, {{k|e}}nable them, then (if you wish) restrict it to stone blocks.

When you've done all that, stop 1 should look like this:

[[File:minecart-example-13.png|Stop 1, defined.]]

Stop 2 is much simpler. All we need to do is have the minecart return to the input stop. So, make a condition and change the direction:

[[File:minecart-example-14.png|Stop 2, defined.]]

Finally, we just have to assign our minecart. Go back to the route definition screen, and press {{k|v}}. Select the minecart, and press {{k|Enter}}.

Now we've got everything set up:

[[File:minecart-example-15.png|Route, fully defined.]]

The V is red because the minecart hasn't been moved onto the track yet. Some dwarf will have to haul it from the forge to the first stop, by hand; this will take a while, especially if the forge is far away.

Once the minecart is in place, dwarves should fill it with blocks from the input stockpile, which will in turn be filled with blocks from the workshop where your mason has been toiling dutifully. When the minecart is full, the blocks will be dumped into the 1x1 stockpile on the right. Automatic quantum dumping!

== Troubleshooting ==

Because of the complexity of the system, all but the most careful and experienced minecart users will encounter issues. Most route issues can be diagnosed and fixed from the {{k|h}}auling menu.

'''Symptom:''' {{DFtext|! Set dir/connect track|6:1}} message appears to the right of one or more stops
<br>'''Possible Causes:'''
* The departure direction of the stop might be invalid. Edit the stop using {{k|Enter}} and press{{k|d}} until it is pointing in a valid direction.
* The track stop might not be built on top of a track. The track stop must be deconstructed to remedy this issue.
* Your track might not be built correctly. Make sure all connected tracks between destinations are not one-way tracks.
** This can be especially confusing with ramps. To carve a two-way track on a (natural) ramp, you must designate the ramp <b>and one square beyond</b> in the direction you want the track to go.
** Ramps '''must''' have a solid block on the side opposite to the track, or they will neither work nor be marked as "unusable". The solid block can be natural or constructed.
* The desired/kept items might not be configured correctly.

'''Symptom:''' The status '''0% <span style="color:#00dd00;">V</span>''' always appears to the right of one stop.
<br>'''Possible Causes:'''
* The stop may not be set to take from a stockpile. Edit the Stop using {{k|Enter}} and make sure you see a message like "Take from Stockpile #1".
* The take conditions must correspond with the contents of the stockpile.
* The track stop may be set to dump. A track stop set to dump cannot be filled. You must either set the stop to a time-based departure or deconstruct the track stop and rebuild it without dumping.
* Make sure the minecart itself has not been designated to be dumped (such as when using mass-dump).

== Capacity ==
Minecarts have five times the capacity of wheelbarrows, which is an enormous amount. A single minecart can carry 2500 rolls of [[cloth]], for example, or even a hundred stone blocks. Unfortunately, loading 2500 [[stone|boulder]]s onto a minecart is not possible (five boulders fit).

A glumprong minecart full with 5 pitchblende boulders weighs 3848Γ, making it useful for weaponized carts if you have these materials available.

[[Water]] and [[magma]] can also be loaded into minecarts by submerging them to a depth of at least 6/7, and dumped by a constructed track stop. Loading fluids onto minecarts can be difficult because their weight can slow the minecart down greatly. Curiously, filling a minecart with magma does not injure a dwarf ''riding'' it. A minecart will hold enough magma to increase the depth of a single tile by 2. This amount is listed as 833 units, which weigh 999Γ. An iron or steel cart filled with magma weighs 1313Γ. An adamantine one weighs 1007Γ.

The capacity in a minecart affects whether a [[pressure plate]] triggers or not, based on the pressure plate's setting.

== Bugs ==

*If you set up lots of routes and stops and then resize your screen, the list will scroll off-screen in the hauling menu. You can still navigate the list with keyboard commands, but cannot see the stop/route name. This will be fixed in the next release.
*A dwarf will drop its [[child|baby]], if it has one, when boarding a minecart set to be ridden.
*Tracks block wagon access to trade depots.{{bug|6040}}
*Dwarves cannot guide a minecart through an unlocked door unless another dwarf opens the door{{bug|6056}}

{{Category|Fortress mode}}
{{Category|Interface}}

[[ru:Minecart]]

v0.31:Exploratory mining

2011-12-09T15:58:07Z

Zilpin:

Once you've had enough [[Losing|fun]] to have a basic fortress working, it becomes necessary to dig down in search of ores, gems, water, etc. Exploratory mining attempts to dig out as little as possible in order to see as much as is possible, using clever digging patterns.

{{av}}{{Quality|Exceptional}}

== Goals ==
Minerals are quite common (as of v0.31.01), reducing the need for extensive exploratory mining to find raw materials. Instead, the goal of most exploratory mining will be finding special features like [[Caverns]] and [[Magma]].
One might want to dig down to the caverns to find drinkable water, if the surface is all saltwater or winter-frozen ponds.

== Dangers ==
Potential dangers include:
*Hostile creatures which inhabit underground areas
*Large pools of liquids ([[Water]], [[Magma]])
*[[Hidden Fun Stuff|Fun]]

==Strategies==
All of the interesting stuff is below you when you start - digging straight down may be the fastest (though not the safest) way to find points of interest.

Those interested in *safely* exploring the depths may wish to create a level every so often where the stairway is broken so you can create barriers (like doors or lever-controlled floodgates) or garrison military squads to deal with any discovered hostiles.

== Exploratory Patterns ==

Patterns are represented by a unit tile. This unit tile is repeated throughout the area intended for excavation to create the desired pattern. Each pattern is analyzed with the above factors in mind.

Key:
. = Mined (floor)
x = Mined (shaft)
░ = Visible, not mined (wall)
▓ = Not mined, not visible

=== Hollow ===
All tiles are excavated.

* ''Labor'': 100% of the tiles are excavated.
* ''Target'': Any size. If it exists in the layer, it will be found.
* ''Visibility'': '''100%''' of the tiles are visible, obviously.
* ''Reusability'': Approaches zero, except for mass storage. Any design other than a large hall requires reconstruction.
* ''Bottom line'': Easy to designate, but miners tend to be a bit chaotic in their approach to the task. Hollowing wastes labor like there's no tomorrow, but integrates extraction into the exploratory mining process. Use only if you have a lot of labor to spare, or need huge amounts of stone and don't mind the reconstruction required to make the hollow area habitable.

=== Rows ===
<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>░░░░░░
......
░░░░░░
░░░░░░
......
░░░░░░</nowiki></div>
* ''Labor'': 1 per every 3 tiles (~33%) of the tiles are excavated.
* ''Target'': Any size. Clusters as small as a single tile are revealed.
* ''Visibility'': '''100%'''.
* ''Reusability'': Very low. The long corridors aren't very useful, and can only be expanded to long, wide corridors. with the right use of walls you can make plenty of 3x3 rooms.
* ''Bottom line'': Easy to designate, and a single miner will focus on one tunnel to the end or they take a [[break]]. This method achieves the same visibility as hollowing out, but using a mere third of the labor. Ideal for hunting single-tile gems. As an added bonus, it is more efficient than a 3×3 design.

Larger "tunnel" patterns are suggested to be dug in multiples of "3" to allow for later complete revealing with minimum effort.

=== Ladder Rows ===
<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>░░░░░░░░░░░░
░░░░░░░░░░░░
░░░░.░░░░░.░
.░..░..░..░.
░.░░░░░.░░░░
░░░░░░░░░░░░
░░░░.░░░░░.░
.░..░..░..░.
░.░░░░░.░░░░
</nowiki></div>
* ''Labor'': 25% of the tiles are excavated (1 in 4).
* ''Target'': Any size. Clusters as small as a single tile are revealed.
* ''Visibility'': '''100%'''.
* ''Reusability'': Moderate. Alternating corridors can be mined out to create 5 tile wide rooms of any length... if the extra doors aren't a concern.
* ''Bottom line'': A little more tedious to designate, but the increased re-usability and efficiency make this an attractive alternative.

=== Diagonal every 5 ===
<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>░░.░░░░.░░
░.░░░░.░░░
.░░░░.░░░░
░░░░.░░░░.
░░░.░░░░.░</nowiki></div>
* ''Labor'': 20% of the tiles are excavated (1 per 5).
* ''Target'': Any size. Clusters as small as a single tile are revealed.
* ''Visibility'': '''100%'''.
* ''Reusability'': With a bit of imagination you can build nice 3x3 rooms
* ''Bottom line'': This method is moderately efficient among those with 100% visibility. This one doesn't use other levels to move from one spot to another but is annoying to designate.

A variation would put diagonals every 10 or 20, laying the groundwork to fill them in later for higher visibility if desired.

=== Mine shafts, grid of every 3 tiles ===

<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>░░░░░░░░░
░X░░X░░X░
░░░░░░░░░
░░░░░░░░░
░X░░X░░X░
░░░░░░░░░</nowiki></div>
* ''Labor'': 11.1% of the tiles are excavated (1/9).
* ''Target'': Any size. Clusters as small as a single tile are revealed.
* ''Visibility'': '''100%'''.
* ''Reusability'': It's easy to make into square rooms of various sizes, the stairways can be removed and used as doorways, or just carved out as part of the rooms.
* ''Bottom line'': You'll need to clear part of one layer to get the shafts started up or down (use one of the other methods to cover the area), but for one shaft at a time this method is, tile for tile, the most efficient for those with 100% visibility, and has a great reuse value. In practice, however, if you have more than one shaft being dug at one time, up/down-mining can cause miners to jump around between shafts, wasting time.

:It takes a lot of keypressing to designate, although you can save some effort by designating every third row (as in the rows method, except with stairways) and then removing the designations ({{k|d}}-{{k|x}}) on all but every third column. Alternately, [[User:StrawberryBunny/Mineshaft.ahk|here]] is a ahk script to save your fingers. Or, you could hold down the left mouse button (designating your staircases) whilst changing Z-levels. You'll still need to do it for each shaft individually, but it can be very time-saving.

''For a discussion on optimizing travel times through mineshafts, see [[Mineshaft stitching]].''

=== Diagonal ramps ===

The pattern as shown is 1 up-ramp every 7 tiles vertically, or 1/14 horizontally, though this could be turned 90 degrees. The downramps are shown, but are only designated on the next level down. (Be ''sure'' you know how [[ramp]]s work before trying this one!)

<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>░░▼░░░░░░░░░░▲░░▼░░░░░░░░░░▲
░░░░░░░░░▲░░▼░░░░░░░░░░▲░░▼░
░░░░░▲░░▼░░░░░░░░░░▲░░▼░░░░░
░▲░░▼░░░░░░░░░░▲░░▼░░░░░░░░░
▼░░░░░░░░░░▲░░▼░░░░░░░░░░▲░░
░░░░░░░▲░░▼░░░░░░░░░░▲░░▼░░░
░░░▲░░▼░░░░░░░░░░▲░░▼░░░░░░░
░░▼░░░░░░░░░░▲░░▼░░░░░░░░░░▲</nowiki></div>
* ''Labor'': 14.3% of the tiles are excavated (1/7).
* ''Target'': Any size. Clusters as small as a single tile are revealed.
* ''Visibility'': '''100%'''.
* ''Reusability'': Moderate. 3x3 spaces cannot be created until at least one up-ramp is removed or a down-ramp floored over. [[Ramp]]s are less convenient than stairs for many purposes (for example, digging out the wrong tiles around a ramp can make it unusable).
* ''Bottom line'': In some ways the most efficient method of all, but difficult to designate and somewhat inconvenient (especially around the edges of the map). Awkward to stitch together.

=== Pinwheel Shafts===

<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>░░░░░░░░░░░
░XX░░X░░XX░
░░░░░X░░░░░
░░░▓░░░▓░░░
░X░░░░░░░X░
░X░░XXX░░X░
░X░░░░░░░X░
░░░▓░░░▓░░░
░░░░░X░░░░░
░XX░░X░░XX░
░░░░░░░░░░░</nowiki></div>
* ''Labor'': In this example about 17.3% of the tiles are being excavated.
* ''Target'': All except single-tile targets are guaranteed to be found, and those will only rarely be missed.
* ''Visibility'': '''96.6%'''.
* ''Reusability'': Workshops can be easily fitted into the unmined 3x3 areas.
* ''Bottom line'': Very similar to Mine Shafts, but you can replace the up/down stairways with alternating up stairs and down stairs on different levels, eliminating the chance that one of your dwarves will slip and fall all the way down the shaft to their deaths.

=== 7×7 blocks ===
<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>▓▓▓░.░▓▓▓▓▓░.░▓▓
░░░░.░░░░░░░.░░░
................
░░░░.░░░░░░░.░░░
▓▓▓░.░▓▓▓▓▓░.░▓▓
▓▓▓░.░▓▓▓▓▓░.░▓▓
▓▓▓░.░▓▓▓▓▓░.░▓▓
▓▓▓░.░▓▓▓▓▓░.░▓▓
▓▓▓░.░▓▓▓▓▓░.░▓▓
░░░░.░░░░░░░.░░░
................
░░░░.░░░░░░░.░░░
▓▓▓░.░▓▓▓▓▓░.░▓▓
▓▓▓░.░▓▓▓▓▓░.░▓▓</nowiki></div>
* ''Labor'': 15/64 (~23%) of the tiles are excavated.
* ''Target'': Veins and up, as the large 5X5 space left in each unit tile can easily conceal a small cluster. Small clusters will be found perhaps half the time.
* ''Visibility'': 39/64 (~61%) of the tiles are visible.
* ''Reusability'': Medium. The 7×7 blocks can easily be converted into 5×5 rooms, suitable for individual rooms, storage or workshops. Optionally, it can be converted into a grid of connected 7×7 rooms, if you center each room on a crossroad; or similarly into a grid of 3x3 rooms, good for workshops, etc. Easily converted into a more thorough 3×3 block patten by digging through the large blocks.
* ''Bottom line'': This is a low-labor method great for vein-hunting. The low labor cost puts you in a position to invest more and get better coverage if desired.

If you think you may wish to later use the "rows" method (above) for 100% visibility, this could be based on a spacing of 6, 9, or 12. Wider spacing starts to risk missing even veins.

=== 15×15 blocks ===
<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
░░░░░.░░░░░░░░░░░░░░░.░░░░░░░░░░
................................
░░░░░.░░░░░░░░░░░░░░░.░░░░░░░░░░
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓
▓▓▓▓░.░▓▓▓▓▓▓▓▓▓▓▓▓▓░.░▓▓▓▓▓▓▓▓▓</nowiki></div>
* ''Labor'': 31/256 (~12%) of the tiles are excavated.
* ''Target'': Large clusters are guaranteed, and unless you have particularly bad luck you should also find all veins, but there is no guarantee. Veins would only rarely be hidden in the large 13×13 space left. The large 13×13 space left in each unit tile can easily conceal quite a lot.
* ''Visibility'': 87/256 (34%) of the tiles are visible.
* ''Reusability'': High. A 15×15 block of solid rock is extremely versatile when it comes to interior design. It's easily converted into a 7×7 block design, which may be further converted into a 3×3 block design.
* ''Bottom line'': This method is preferable when you are low on labor. It can easily accommodate parts of your fort, or serve as the precursor for a more thorough search. A 12×12 or 18×18 version are also valid options, with obvious (dis)advantages.

=== Mine Shafts on a 6-, 9-, 12-, or 15-grid ===

<div style="font-family: monospace; white-space: pre; line-height: 126.5%"><nowiki>▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓░░░▓▓▓▓▓▓▓▓▓▓▓▓▓░░░▓▓▓▓
▓▓▓▓▓░X░▓▓▓▓▓▓▓▓▓▓▓▓▓░X░▓▓▓▓
▓▓▓▓▓░░░▓▓▓▓▓▓▓▓▓▓▓▓▓░░░▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓░░░▓▓▓▓▓▓▓▓▓▓▓▓▓░░░▓▓▓▓
▓▓▓▓▓░X░▓▓▓▓▓▓▓▓▓▓▓▓▓░X░▓▓▓▓
▓▓▓▓▓░░░▓▓▓▓▓▓▓▓▓▓▓▓▓░░░▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓</nowiki></div>
* ''Labor'': from under 3% (1/36) for the 6-grid to less than 0.5% for the 15-grid (1/225).
* ''Target'': Large clusters and up (as above) and underground features.
* ''Visibility'': from 25% for the 6-grid to 4% for the 15-grid.
* ''Reusability'': High. Any area often needs a set of stairs (or more than one) leading up/down, and these would be the start of them.
* ''Bottom line'': This method should be used when you are looking for [[caverns]], or getting a feel for the various rock layers, or just hoping to get lucky with little effort. Grids larger than 15 may start to miss even large features such as large clusters, but can be used for identifying stone layers, and can always be filled back in later with shafts on a tighter grid.

With any grid pattern, a (much) wider version could be used to start and to locate specific stone layers/areas, and then filled in later in a tighter pattern where you want if you're not lucky the first pass. If you plan to use the 3-grid pattern (for a 100% tile reveal) later, create your grid with intervals that are a multiple of "3". If you are only looking for veins, features or just don't care, then do as you will and play it by ear later.

----
== Mountain Top Removal Excavation ==
When the fortress is large enough, nearly every dwarf is standing idle, your have plenty of picks, and just want to mine it all ([[Elf|Environmentalist Hippies]] can go to HFS!), complete excavation may be in order. The risk of cave-in or stranded dwarfs prevents simply designating an entire mountain Channel, but mining the whole thing can be done with minimum player effort.

* Designate up-down stairs on the entire area to excavate, on every z-level. Designate the lowest level up-stairs, and leave a single tile one z-level above undesignated.
* Let the dwarfs mine it.
* If any walls are attached to the outermost edge of the excavation area, designate all of the edge stairs Channel to remove them (dwarfs will mine them from the neighboring stairs).
* Designate the lowest z-level for Remove Up Stairs. Leave one to prevent cave-in!
* Build a support under the unmined tile (remember step #1?). Remove the last up stair, once everyone is out of the stairs above.
* Link a lever far away, keep away all the <strike>suicidal idiots</strike> dwarfs and pull it.

After a long wait, the entire block of stairs will collapse, leaving the entire area safely excavated. The lever can now be removed, and all goodies from an entire mountain can be collected.
----

{{Category|Guides}}

v0.31:Reactions

2010-10-05T18:04:32Z

Zilpin: /* Reactions and world generation */

{{quality|Masterwork|08:00, 22 May 2010 (UTC)}}
{{av}}

Reactions are modular, editable formulas that take specific ingredients, or reagents, and use them to produce a desired item. A lot of reactions are hardcoded - building beds or creating glass, for example -- but a few are freely editable, and it's quite simple to add additional ones.

== Reaction differences between modes ==
In [[Fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[Entities|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction -- so that if you give your custom civilization a reaction to produce star metal or some other custom material, only they will be able to use it.

In [[Adventure mode]], reactions are freely available via x > create, and any adventurer character can make free use of them. Reagents may be held in the hands or dropped on the ground, but cannot be used within a backpack or quiver. As of .10, there are several bugs with Adventure mode reactions, chief of which is the fact that the [HAS_MATERIAL_REACTION_PRODUCT] token is completely ignored, leading to dragon eye tissue tanned hides, among other things.

Prior to version 31.10, a reaction could only result in an object of base [[quality]]. However, in .10 items produced via reactions have been observed to have quality modifiers. The way skill factors into them has yet to be determined.

==Anatomy of a reaction==

Reactions are found within reaction_x files (such as reaction_smelter or reaction_other). Generally speaking they adhere to the following structure:

[REACTION:<REACTION IDENTIFIER>]
[NAME:<REACTION NAME>]
[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
The building that the reaction uses, and the relevant
keyboard shortcut.
[REAGENT:A:150:BAR:NONE:POTASH:NONE]
The ingredients required for the reaction.
[PRODUCT:100:1:BAR:NONE:PEARLASH:NONE][PRODUCT_DIMENSION:150]
The exact item produced by the reaction.
[FUEL]
Whether or not the reaction requires charcoal, coke or
a magma-powered workshop.
[#SKILL:<SKILL TOKEN>]
The skill required and trained by the reaction.
[AUTOMATIC]

The <REACTION IDENTIFIER> may be anything, so long as it is unique within the raws - a good habit to get into is to append a short term to the end of each name related to the name of your mod, to ensure nobody else is going to make an identical reaction and thereby mess up the game if their mod is run alongside yours.

The <REACTION NAME> can be anything at all, and is usually used to describe the reaction - 'tan a hide', for example, is the name of the default leather-producing reaction.

The BUILDING NAME is the name of the building that will house this reaction, and the building key is the keyboard shortcut that will queue up the reaction. If two reactions have the same key, then one of them will be assigned a different key, the first alphabetically available at the building.

=== Reagents ===
REAGENTs are a little bit complicated. They are the ingredients that the reaction will use. You can define as many as you like within a reaction so long as they all have unique names.

[REAGENT:<name>:<quantity>:<item token>:<item subtype>:<material token>:<material subtype>]

The name field is just a small string used to refer to the reagent within the reaction; 'A' or 'B' work, as do words like 'toolstone' or 'flux' - remember not to use apostrophes, though.

The quantity differs between item types - generally speaking, cloth, thread, powder and globs use numbers representing the size of material within one item, and everything else uses a static quantity. For example, 10 thread is one extremely tiny unit of thread, but 10 toy is ten unique, solid toy items.

NOTE: Sometimes the quantity of product is directly connected with the quantity of reagent; it seems to be REAGENT <quantity> / 150 (rounding down) so that Reagent <quantity> of 3 gives 50 product and a <quantity> of 4 gives 37. (150/4=37.5)

The item token is the type of item you require - WEAPON, TOY or SKIN_TANNED, for example.

The item subtype is the exact item that you require - ITEM_WEAPON_SPEAR or ITEM_TOY_PUZZLEBOX, as examples. Some items, like quivers or backpacks, or chunks of stone or metal, only require the item token to be filled in, so if you're asking for those you can leave this blank.

The material token and material subtype are frequently related. The first indicates the category of material you want, such as INORGANIC, though it can also specify one of the hardcoded materials (see {{L|material token}} for a list). The second indicates the specific subtype of material you want, such as OBSIDIAN or STEEL.

Reagents may also have extra tokens added on afterwards. A list of them follows:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [PRESERVE_REAGENT]
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
|-
| [REACTION_CLASS:X]
| Detailed below the reaction anatomy section.
|-
| [HAS_MATERIAL_REACTION_PRODUCT:X]
| Detailed below the reaction anatomy section.
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic MATGLOSS types.
|-
| [BUILDMAT]
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
|-
| [GLASS_MATERIAL]
| Reagent has a one of the glass MATGLOSS types.
|-
| [WORTHLESS_STONE_ONLY]
| The reagent respects allowed and forbidden economic stones from the Stone menu.
|-
| [FIRE_BUILD_SAFE]
| Reagent must be considered fire safe - ie. not wood, and not coal.
|-
| [MAGMA_BUILD_SAFE]
| Reagent must have a melting point greater than the temperature of Magma.
|-
| [CAN_USE_ARTIFACT]
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
|-
| [ANY_PLANT_MATERIAL]
| Reagent MATGLOSS must be of a plant subtype.
|-
| [ANY_SILK_MATERIAL]
| Reagent MATGLOSS must be of a silk type.
|-
| [ANY_SOAP_MATERIAL]
| Reagent MATGLOSS must be of a soap type.
|-
| [ANY_LEATHER_MATERIAL]
| Reagent MATGLOSS must be of a leather type.
|-
| [ANY_BONE_MATERIAL]
| Reagent MATGLOSS must be of a bone type.
|-
| [ANY_SHELL_MATERIAL]
| Reagent MATGLOSS must be of a shell type.
|-
| [ANY_TOOTH_MATERIAL]
| Reagent MATGLOSS must be of a tooth type.
|-
| [ANY_HORN_MATERIAL]
| Reagent MATGLOSS must be of a horn type.
|-
| [ANY_PEARL_MATERIAL]
| Reagent MATGLOSS must be of a pearl type (Excretion from sea creatures?)
|-
| [USE_BODY_COMPONENT]
| Reagent MATGLOSS must come off a creature's body.
|-
| [METAL_ORE]
| Reagent MATGLOSS must be a metal ore.
|-
| [NOT_WEB]
| States that the material cannot be web (For making only plant/adamantine thread?).
|-
| [WEB_ONLY]
| States that the material has to be web (For making only silk thread?).
|-
| [POTASHABLE]
| The reagent must be able to be turned into pot ash.
|-
| [EMPTY]
| If the reagent is a container, it must be empty.
|-
| [CONTAINS_LYE]
| If the reagent is a container, it must contain LYE.
|-
| [NOT_CONTAIN_BARREL_ITEM]
| If the reagent is a Barrel, it must not contain an item that has to reside in a barrel. Barrel items appear to be lye and milk. Alcohol appears to be covered as part of [EMPTY]. A reaction which places an item in a barrel should probably have both tags.
|-
| [BAG]
| Reagent has to be a bag. Intended to be used with an item type of BOX, to prevent chests, coffers, and other containers from being used instead.
|}

Generally speaking, if you set a field in a reagent to NONE, the reaction won't discriminate when it comes to that particular field. For example, if you require a BOULDER reagent but leave the matgloss fields as NONE:NONE, it will grab any available BOULDER-type item irrespective of matgloss.

===Products===
Products are the end product of the reaction. A reaction can have as many products as it likes.

Products are almost identical to reagents, except that they do not need to be named, can't have fields undefined, and don't use the quantity field to determine the product size. Instead, the token PRODUCT_DIMENSION:X is tacked on after the PRODUCT token, determining the size of the product. Products also don't use tokens like USE_ANY_BONE_MATERIAL.

Products can be produced directly to a container using the [PRODUCT_TO_CONTAINER:<IDENTIFIER>] token, where the IDENTIFIER is the name of a reagent. This requires the reagent to have the PRESERVE_REAGENT token.

===Other tokens===
The [FUEL] token means that the reaction requires coke or charcoal to be performed, or theoretically magma, if we could build magma workshops.

The [SKILL:X] token determines what [[Skill tokens|skill]] the reaction requires and what skill it trains. Multiple skills can be listed but only one will be used.

The [AUTOMATIC] token means that the reaction will be queued automatically if the reaction reagents are all present.

The [ADVENTURE_MODE_ENABLED] token means that this version of the reaction is not used by dwarves at home in a fortress, but rather the wanderers of Adventure Mode. When using this token, it will be allowed for adventurers of any race, without editing Entity files.

==Material reaction products and reaction classes==

You can get a certain measure of control over very specific materials using reaction classes and material reaction products - the tokens look like this:

[REACTION_CLASS:FAT]
[HAS_MATERIAL_REACTION_PRODUCT:RENDER_MAT]

Reaction classes represent different classes of material - basically, the matgloss subtype of the reagent must have a REACTION_CLASS the same as the one in the reaction.

Material reaction products are similar, but are generally used more for things like different kinds of creature materials than universal materials like stone. This token is how skin can be tanned into leather, which are two separate materials - the skin material has leather as a MATERIAL_REACTION_PRODUCT.

In short, they require the material to have a token such as
[MATERIAL_REACTION_PRODUCT:X:Y:Z]
...where X is the name of the reaction product that will be referred to in the reaction (RENDER_MAT, in the reaction class example, or TAN_MAT for leather), Y is the matgloss type of the desired product (such as INORGANIC or LOCAL_CREATURE_MAT) and Z is the specific material, like LEATHER or OBSIDIAN.

==Reactions and world generation==

There are several things to keep in mind when you're adding reactions to a game that already exists.

<br />- Most entity changes require a regen, but adding PERMITTED_REACTION tokens for reactions that existed at the time of world generation to a the entity file in the save directory do not.
<br />- Adding reactions to the raws in a save directory requires you to regen the world.
<br />- You can alter an existing reaction in any way you like without regenning the world, so long as you don't alter the reaction identifier.
<br /><br />
--[[User:Zilpin|Zilpin]] 18:04, 5 October 2010 (UTC)
(there is a utility to add new buildings and reactions to a savegame, using its raws. needs objective third party review.)
[http://www.bay12forums.com/smf/index.php?topic=67059.0]

[[Category:DF2010:Modding]]

File:Rawadammount-Dwarf Fortress.jpg

2010-09-29T01:40:55Z

Zilpin: An example of swapping materials using dfworldtinker

An example of swapping materials using dfworldtinker

v0.31:Advanced world generation

2010-05-27T15:09:02Z

Zilpin: /* Z Levels */

{{quality|Fine|08:00, 22 May 2010 (UTC)}}{{av}}
= Advanced Parameters =

To access advanced parameters, press {{key|e}} when at the screen for creating new worlds with parameters screen. This will bring you to an editable list of various guidelines the world-gen process will use when creating your new world.

Parameter sets are stored in ''world_gen.txt'' in the ''\data\init'' folder, using [[world tokens]]. You can copy and paste other player's sets of parameters into your ''world_gen.txt'' to use their parameter sets, and some are provided at [[Pregenerated worlds]]. Another place to find parameter sets is the [http://www.bay12games.com/forum/index.php?topic=20638.0 Worldgen cookbook] thread on the official forums.

== Caverns Parameters ==

=== Cavern Layer Number ===

This parameter determines how many cavern systems will be generated, not including the Magma layer or the Bottom layer. Defaults to three.

If this is 0 then you will not have Caverns on your map.

Example:<blockquote>
[CAVERN_LAYER_COUNT:3]
</blockquote>

=== Layer Openness min\max ===

Still unknown. It doesn't seem to affect whether there's a wall at the edge of the map, but it may affect whether creatures will come in through the edges.

Example:<blockquote>
[CAVERN_LAYER_OPENNESS_MIN:0]<br />
[CAVERN_LAYER_OPENNESS_MAX:100]
</blockquote>

=== Layer Passage Density min\max ===

This determines whether caverns will be large open spaces (at 0), or broken up into a number of small vertical shafts(at 100).

Example:<blockquote>
[CAVERN_LAYER_PASSAGE_DENSITY_MIN:0]<br />
[CAVERN_LAYER_PASSAGE_DENSITY_MAX:100]
</blockquote>

=== Layer Watern min\max ===

Determines how many caverns will have water at the bottom. Note that, even at 100, there will be some amount of ground in caverns, but each cavern 'bubble' will contain some amount of water.

At 0, there will be no water in your caverns. This may impact future underground plant growth, although maps will still start with underground flora.

Example:<blockquote>[CAVERN_LAYER_WATER_MIN:0]<br />
[CAVERN_LAYER_WATER_MAX:100]
</blockquote>

=== Magma Layer ===

Magma sea 4-5 layers at the bottom of map.

Value 1 forces magma layer, value 0 appears to prevent it.
<br />Appears not have impact on volcanoes, nor vulcanism, so even if 0 there will still be emark locations with magma.
<br />If a volcano exists, it appears to always tap the magma sea, but the magma see will not be revealed by revealing the volcano.
<br />(Unconfirmed whether magma layer still can occur if HFS exists in a specific embark tile, e.g. Temple).

Example:<blockquote>[HAVE_BOTTOM_LAYER_1:1]
</blockquote>

=== Bottom Layer ===

Cavern below magma sea.
If "yes" the "HFS" layer is always present.
Defaults to "yes".

If turned on, will force the magma layer above it.
<br />(Unknown whether this has any impact on occurrence of Clown Castle)

Example:<blockquote>[HAVE_BOTTOM_LAYER_2:1]
</blockquote>

=== Z Levels ===
'''[Previous table clear as mud; this table murky pool.]'''

Following table based on having 3 cavern layers. The Levels Above Layer settings control how many Z-Levels are above each layer. A layer may itself consist of multiple Z-Levels (and almost always does).

{|style="margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;" class="wikitable"
|-style="background:#F2F2F2;text-align:center;"
!style="border:1px #AAA solid;padding:0.2em;" width="120"|Setting Name
!style="border:1px #AAA solid;padding:0.2em;" width="200"|file tag
!style="border:1px #AAA solid;padding:0.2em;"| Description
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Ground
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_GROUND
|style="border:1px #AAA solid;padding:0.2em;"| The number of Z-Levels of air above the highest surface level.<br />Has no impact on how many Z-levels deep the surface layer is.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above layer 1
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_1
|style="border:1px #AAA solid;padding:0.2em;"| Z-Levels of stone above the first cavern layer. Making this higher will guarantee ''at least'' this many levels to build your fortress, but will have no impact on how many z-levels thick the surface layer is. Also, the top of a cavern may be higher than the rest of a cavern, so in practice there will be more levels than this.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 2
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_2
|style="border:1px #AAA solid;padding:0.2em;"| Z-levels of earth between very top of second cavern and very bottom of first cavern.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 3
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_3
|style="border:1px #AAA solid;padding:0.2em;"| Z-levels of earth between very top of third cavern and very bottom of second cavern.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 4
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_4
|style="border:1px #AAA solid;padding:0.2em;"| Z-Levels of earth between very highest magma and very bottom of third cavern.<br />Spoiler Hidden: 
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 5
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_5
|style="border:1px #AAA solid;padding:0.2em;"| Uncertain. May control the number of levels of "Semi Molten Rock" between HFS and Magma, may control number of levels of magma, may impact both.<br />In experimentation, the overall depth of all magma sea and semi-molten rock levels appears to increase, but not consistent enough to say for certain.<br />Only valid if Magma Layer present.<br />Spoiler Hidden:
|-
|style="border:1px #AAA solid;padding:0.2em;"| At Bottom
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_AT_BOTTOM
|style="border:1px #AAA solid;padding:0.2em;"| Appears to be number of levels of HFS chamber.<br />Only valid if Bottom Layer present.<br />Often has no impact.<br />Values larger than default results in strange things.
|-
|}

Some implications:
* The number of surface layers (e.g. soil), at this time, can not be controlled. For example, on a map with 1 layer of Peat, then a layer of Silt, then a layer of Obsidian, there is no control to let you increase either one to be, say, 20 z-levels. (though you may get lucky with the Obsidian).
* There can be multiple stone layers between the cavern and the surface. So increasing Levels Above Layer 1 may give you more Conglomerate, or more Granite, and you have no control over which stone layer spans those Z-Levels.
* The layers shown on embark span across the cavern layers in an unknown and inconsistent way. Sometimes those 10 different layers of stone are evenly distributed over your 400 z-level deep map, sometimes the first 9 get 1 z-level each and the last gets the other 391 levels. No way to control found yet.
* The HFS temple, if present, will always extend into the rock layers, and appears to always make contact with the bottom cave. Large values for levels above layer 5 and layer 4 can result in enormous temples, but the number of levels at the top (the part with undead) appears to be unaffected.
* Unconfirmed whether number of levels between caverns has any impact on cavern height. There will be connecting ramps and/or shafts between cavern layers no matter how many levels are between them.
* '''Very Important''': These values appear to apply across a whole 16x16 Region, not just embark areas. That means that if a 16x16 region is completely flat, but has one tall mountain in one far corner, even if you set Levels Above Ground low (e.g. 2 z-levels) you still have all the empty air of the highest mountain in every embark tile (e.g. 200 z-levels). Also can happen to the semi-molten layer, and can lead to unexpected behavior.
* Very large values can cause strange things to happen. Even more true for small values.

v0.31:Advanced world generation

2010-05-27T14:28:40Z

Zilpin: /* Magma Layer */

{{quality|Fine|08:00, 22 May 2010 (UTC)}}{{av}}
= Advanced Parameters =

To access advanced parameters, press {{key|e}} when at the screen for creating new worlds with parameters screen. This will bring you to an editable list of various guidelines the world-gen process will use when creating your new world.

Parameter sets are stored in ''world_gen.txt'' in the ''\data\init'' folder, using [[world tokens]]. You can copy and paste other player's sets of parameters into your ''world_gen.txt'' to use their parameter sets, and some are provided at [[Pregenerated worlds]]. Another place to find parameter sets is the [http://www.bay12games.com/forum/index.php?topic=20638.0 Worldgen cookbook] thread on the official forums.

== Caverns Parameters ==

=== Cavern Layer Number ===

This parameter determines how many cavern systems will be generated, not including the Magma layer or the Bottom layer. Defaults to three.

If this is 0 then you will not have Caverns on your map.

Example:<blockquote>
[CAVERN_LAYER_COUNT:3]
</blockquote>

=== Layer Openness min\max ===

Still unknown. It doesn't seem to affect whether there's a wall at the edge of the map, but it may affect whether creatures will come in through the edges.

Example:<blockquote>
[CAVERN_LAYER_OPENNESS_MIN:0]<br />
[CAVERN_LAYER_OPENNESS_MAX:100]
</blockquote>

=== Layer Passage Density min\max ===

This determines whether caverns will be large open spaces (at 0), or broken up into a number of small vertical shafts(at 100).

Example:<blockquote>
[CAVERN_LAYER_PASSAGE_DENSITY_MIN:0]<br />
[CAVERN_LAYER_PASSAGE_DENSITY_MAX:100]
</blockquote>

=== Layer Watern min\max ===

Determines how many caverns will have water at the bottom. Note that, even at 100, there will be some amount of ground in caverns, but each cavern 'bubble' will contain some amount of water.

At 0, there will be no water in your caverns. This may impact future underground plant growth, although maps will still start with underground flora.

Example:<blockquote>[CAVERN_LAYER_WATER_MIN:0]<br />
[CAVERN_LAYER_WATER_MAX:100]
</blockquote>

=== Magma Layer ===

Magma sea 4-5 layers at the bottom of map.

Value 1 forces magma layer, value 0 appears to prevent it.
<br />Appears not have impact on volcanoes, nor vulcanism, so even if 0 there will still be emark locations with magma.
<br />If a volcano exists, it appears to always tap the magma sea, but the magma see will not be revealed by revealing the volcano.
<br />(Unconfirmed whether magma layer still can occur if HFS exists in a specific embark tile, e.g. Temple).

Example:<blockquote>[HAVE_BOTTOM_LAYER_1:1]
</blockquote>

=== Bottom Layer ===

Cavern below magma sea.
If "yes" the "HFS" layer is always present.
Defaults to "yes".

If turned on, will force the magma layer above it.
<br />(Unknown whether this has any impact on occurrence of Clown Castle)

Example:<blockquote>[HAVE_BOTTOM_LAYER_2:1]
</blockquote>

=== Z Levels ===
'''[Previous table clear as mud; this table murky pool.]'''

Following table based on having 3 cavern layers. The Levels Above Layer settings control how many Z-Levels are above each layer. A layer may itself consist of multiple Z-Levels (and almost always does).

{|style="margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;" class="wikitable"
|-style="background:#F2F2F2;text-align:center;"
!style="border:1px #AAA solid;padding:0.2em;" width="120"|Setting Name
!style="border:1px #AAA solid;padding:0.2em;" width="200"|file tag
!style="border:1px #AAA solid;padding:0.2em;"| Description
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Ground
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_GROUND
|style="border:1px #AAA solid;padding:0.2em;"| The number of Z-Levels of air above the highest surface level.<br />Has no impact on how many Z-levels deep the surface layer is.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above layer 1
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_1
|style="border:1px #AAA solid;padding:0.2em;"| Z-Levels of stone above the first cavern layer. Making this higher will guarantee ''at least'' this many levels to build your fortress, but will have no impact on how many z-levels thick the surface layer is. Also, the top of a cavern may be higher than the rest of a cavern, so in practice there will be more levels than this.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 2
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_2
|style="border:1px #AAA solid;padding:0.2em;"| Z-levels of earth between very top of second cavern and very bottom of first cavern.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 3
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_3
|style="border:1px #AAA solid;padding:0.2em;"| Z-levels of earth between very top of third cavern and very bottom of second cavern.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 4
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_4
|style="border:1px #AAA solid;padding:0.2em;"| Z-Levels of earth between very highest magma and very bottom of third cavern.<br />Spoiler Hidden: 
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 5
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_5
|style="border:1px #AAA solid;padding:0.2em;"| Uncertain. May control the number of levels of "Semi Molten Rock" between HFS and Magma, may control number of levels of magma, may impact both.<br />In experimentation, the overall depth of all magma sea and semi-molten rock levels appears to increase, but not consistent enough to say for certain.<br />Only valid if Magma Layer present.<br />Spoiler Hidden:
|-
|style="border:1px #AAA solid;padding:0.2em;"| At Bottom
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_AT_BOTTOM
|style="border:1px #AAA solid;padding:0.2em;"| Appears to be number of levels of HFS chamber.<br />Only valid if Bottom Layer present.<br />Often has no impact.<br />Values larger than default results in strange things.
|-
|}

Some implications:
* The number of surface layers (e.g. soil), at this time, can not be controlled. For example, on a map with 1 layer of Peat, then a layer of Silt, then a layer of Obsidian, there is no control to let you increase either one to be, say, 20 z-levels. (though you may get lucky with the Obsidian).
* There can be multiple stone layers between the cavern and the surface. So increasing Levels Above Layer 1 may give you more Conglomerate, or more Granite, and you have no control over which stone layer spans those Z-Levels.
* The layers shown on embark span across the cavern layers in an unknown and inconsistent way. Sometimes those 10 different layers of stone are evenly distributed over your 400 z-level deep map, sometimes the first 9 get 1 z-level each and the last gets the other 391 levels. No way to control found yet.
* The HFS temple, if present, will always extend into the rock layers, and appears to always make contact with the bottom cave. Large values for levels above layer 5 and layer 4 can result in enormous temples, but the number of levels at the top (the part with undead) appears to be unaffected.
* Unconfirmed whether number of levels between caverns has any impact on cavern height. There will be connecting ramps and/or shafts between cavern layers no matter how many levels are between them.
* Very large values can cause strange things to happen. Even more true for small values.

v0.31:Advanced world generation

2010-05-27T14:28:05Z

Zilpin: /* Z Levels */

{{quality|Fine|08:00, 22 May 2010 (UTC)}}{{av}}
= Advanced Parameters =

To access advanced parameters, press {{key|e}} when at the screen for creating new worlds with parameters screen. This will bring you to an editable list of various guidelines the world-gen process will use when creating your new world.

Parameter sets are stored in ''world_gen.txt'' in the ''\data\init'' folder, using [[world tokens]]. You can copy and paste other player's sets of parameters into your ''world_gen.txt'' to use their parameter sets, and some are provided at [[Pregenerated worlds]]. Another place to find parameter sets is the [http://www.bay12games.com/forum/index.php?topic=20638.0 Worldgen cookbook] thread on the official forums.

== Caverns Parameters ==

=== Cavern Layer Number ===

This parameter determines how many cavern systems will be generated, not including the Magma layer or the Bottom layer. Defaults to three.

If this is 0 then you will not have Caverns on your map.

Example:<blockquote>
[CAVERN_LAYER_COUNT:3]
</blockquote>

=== Layer Openness min\max ===

Still unknown. It doesn't seem to affect whether there's a wall at the edge of the map, but it may affect whether creatures will come in through the edges.

Example:<blockquote>
[CAVERN_LAYER_OPENNESS_MIN:0]<br />
[CAVERN_LAYER_OPENNESS_MAX:100]
</blockquote>

=== Layer Passage Density min\max ===

This determines whether caverns will be large open spaces (at 0), or broken up into a number of small vertical shafts(at 100).

Example:<blockquote>
[CAVERN_LAYER_PASSAGE_DENSITY_MIN:0]<br />
[CAVERN_LAYER_PASSAGE_DENSITY_MAX:100]
</blockquote>

=== Layer Watern min\max ===

Determines how many caverns will have water at the bottom. Note that, even at 100, there will be some amount of ground in caverns, but each cavern 'bubble' will contain some amount of water.

At 0, there will be no water in your caverns. This may impact future underground plant growth, although maps will still start with underground flora.

Example:<blockquote>[CAVERN_LAYER_WATER_MIN:0]<br />
[CAVERN_LAYER_WATER_MAX:100]
</blockquote>

=== Magma Layer ===

Magma sea 4-5 layers at the bottom of map.

Value 1 forces magma layer, value 0 appears to prevent it.
<br />Appears not have impact on volcanoes, nor vulcanism, so even if 0 there will still be emark locations with magma.
<br />If a volcano exists, it appears to always tap the magma sea, but the magma see will not be revealed by revealing the volcano.
<br />(Unconfirmed whether magma layer still can occur if HFS exists in a specific embark tile, e.g. Clown Castle).

Example:<blockquote>[HAVE_BOTTOM_LAYER_1:1]
</blockquote>

=== Bottom Layer ===

Cavern below magma sea.
If "yes" the "HFS" layer is always present.
Defaults to "yes".

If turned on, will force the magma layer above it.
<br />(Unknown whether this has any impact on occurrence of Clown Castle)

Example:<blockquote>[HAVE_BOTTOM_LAYER_2:1]
</blockquote>

=== Z Levels ===
'''[Previous table clear as mud; this table murky pool.]'''

Following table based on having 3 cavern layers. The Levels Above Layer settings control how many Z-Levels are above each layer. A layer may itself consist of multiple Z-Levels (and almost always does).

{|style="margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;" class="wikitable"
|-style="background:#F2F2F2;text-align:center;"
!style="border:1px #AAA solid;padding:0.2em;" width="120"|Setting Name
!style="border:1px #AAA solid;padding:0.2em;" width="200"|file tag
!style="border:1px #AAA solid;padding:0.2em;"| Description
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Ground
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_GROUND
|style="border:1px #AAA solid;padding:0.2em;"| The number of Z-Levels of air above the highest surface level.<br />Has no impact on how many Z-levels deep the surface layer is.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above layer 1
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_1
|style="border:1px #AAA solid;padding:0.2em;"| Z-Levels of stone above the first cavern layer. Making this higher will guarantee ''at least'' this many levels to build your fortress, but will have no impact on how many z-levels thick the surface layer is. Also, the top of a cavern may be higher than the rest of a cavern, so in practice there will be more levels than this.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 2
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_2
|style="border:1px #AAA solid;padding:0.2em;"| Z-levels of earth between very top of second cavern and very bottom of first cavern.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 3
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_3
|style="border:1px #AAA solid;padding:0.2em;"| Z-levels of earth between very top of third cavern and very bottom of second cavern.
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 4
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_4
|style="border:1px #AAA solid;padding:0.2em;"| Z-Levels of earth between very highest magma and very bottom of third cavern.<br />Spoiler Hidden: 
|-
|style="border:1px #AAA solid;padding:0.2em;"| Above Layer 5
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_ABOVE_LAYER_5
|style="border:1px #AAA solid;padding:0.2em;"| Uncertain. May control the number of levels of "Semi Molten Rock" between HFS and Magma, may control number of levels of magma, may impact both.<br />In experimentation, the overall depth of all magma sea and semi-molten rock levels appears to increase, but not consistent enough to say for certain.<br />Only valid if Magma Layer present.<br />Spoiler Hidden:
|-
|style="border:1px #AAA solid;padding:0.2em;"| At Bottom
|style="border:1px #AAA solid;padding:0.2em;"| LEVELS_AT_BOTTOM
|style="border:1px #AAA solid;padding:0.2em;"| Appears to be number of levels of HFS chamber.<br />Only valid if Bottom Layer present.<br />Often has no impact.<br />Values larger than default results in strange things.
|-
|}

Some implications:
* The number of surface layers (e.g. soil), at this time, can not be controlled. For example, on a map with 1 layer of Peat, then a layer of Silt, then a layer of Obsidian, there is no control to let you increase either one to be, say, 20 z-levels. (though you may get lucky with the Obsidian).
* There can be multiple stone layers between the cavern and the surface. So increasing Levels Above Layer 1 may give you more Conglomerate, or more Granite, and you have no control over which stone layer spans those Z-Levels.
* The layers shown on embark span across the cavern layers in an unknown and inconsistent way. Sometimes those 10 different layers of stone are evenly distributed over your 400 z-level deep map, sometimes the first 9 get 1 z-level each and the last gets the other 391 levels. No way to control found yet.
* The HFS temple, if present, will always extend into the rock layers, and appears to always make contact with the bottom cave. Large values for levels above layer 5 and layer 4 can result in enormous temples, but the number of levels at the top (the part with undead) appears to be unaffected.
* Unconfirmed whether number of levels between caverns has any impact on cavern height. There will be connecting ramps and/or shafts between cavern layers no matter how many levels are between them.
* Very large values can cause strange things to happen. Even more true for small values.