I'll be reading Shaoustul's mod guide thread, but in the meantime, here's a post that I drafted up last night.
There's very little documentation, so I've been trying to deduce the syntax of the raw files. I'm hoping that all this has already been worked out, but let's start with the only building that you get to use as an example from the raws: the Soap Maker's shop.
[BUILDING_WORKSHOP:SOAP_MAKER]
The first argument here clearly indicates that this object is a building, and what sort of building (a workshop). What other building types are possible? Does "BUILDING_SIEGE" make sense to the system? What about "BUILDING_CONSTRUCTION"? And so on? The second argument seems to be the string by which this building is identified for statements that need such an identifier, such as the reactions.
[NAME:Soap Maker's Workshop]
[NAME_COLOR:7:0:1]
These are obvious; the name given for this building, and the color that the name appears in.
[DIM:3:3]
Also obvious; the tile dimensions of the building.
[WORK_LOCATION:2:2]
This one took me a minute. It's the coordinates where a dwarf working in this workshop stands. I'm guessing it's relative to the top left corner?
[BUILD_LABOR:SOAP_MAKER]
This is the labor needed to construct the building, yes? As in, you must have a dwarf with "Soap maker" activated in his Pref->Labor menu.
[BUILD_KEY:CUSTOM_SHIFT_S]
The hotkey used for this building in the building menu. Apparently it parses that this building is a "WORKSHOP" and thus knows to put this hotkey in the Building->Workshop menu.
[BLOCK:1:0:0:0]
[BLOCK:2:0:0:0]
[BLOCK:3:0:0:0]
I got no clue here. Is this maybe the tiles in this workshop that obstruct dwarves?
[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]
I get this. This is the graphics used to represent this workshop in the varying stages of its construction. Although the color arguments have me confused. Why not just a simple RGB? I figured out that part of it is "background" color, and another part "foreground" color, but I'm not sure what's what because I don't know what the numbers mean. Also, there's 11 arguments, so there's at least a third factor involved here. The only thing I can think would be an alpha or gamma value, which would be nonsensical in this game (which, I'm guessing, is probably why the final arguments in these are always zero).
[BUILD_ITEM:1:BUCKET:NONE:NONE:NONE][EMPTY][CAN_USE_ARTIFACT]
The first bit, "BUILD_ITEM" means item requisite for building this.
The "1" seems to be the amount of this item required.
The argument "BUCKET" seems to be the type of item. What values are valid for this argument? BUCKET, BAR, BLOCK, METAL_ORE, WOOD, BOULDER, and BARREL are all things I've seen in tags that seem to have this same syntax. What else works? WEAPON? AMMO? CRAFT? INSTRUMENT? Help me out here.
I don't yet have an understanding of the next three arguments, which are all null values here. I've been trying to piece them together from the tags in the reaction raws that seem to have the same syntax, but I haven't got a handle on it.
The [EMPTY] tag means that the bucket must be empty. I'm guessing this works for other containers that might be requisite for a building? For instance, BAG, BARREL, CHEST, or CABINET?
The [CAN_USE_ARTIFACT] clearly allows artifact buckets to be used for this purpose. Which I'm assuming is a good way to jack up your Wealth->Architecture, yes?
[BUILD_ITEM:1:NONE:NONE:NONE:NONE][BUILDMAT][WORTHLESS_STONE_ONLY][CAN_USE_ARTIFACT]
The fact that the "item type" is null here -- that must mean that it doesn't matter whether it's a block, bar, metal ore, or boulder. In fact, it would appear that it wouldn't matter what it is *at all* if not for the [BUILDMAT] tag that clearly is to indicate that only building materials (blocks, bars, metal ores, and boulders) can be used. [WORTHLESS_STONE_ONLY] must be to prevent you from using economic stones.
(And we've been over [CAN_USE_ARTIFACT], but, I gotta ask: has anyone ended up with an artifact bar or block? Seems a bit anticlimactic for a dwarf to get possessed and make a block.)
After this, I've still got some questions about modding buildings. Like, what's the tag to require a fire-safe material, as with furnaces?
Now let's look at a reaction. Just to grab one, let's say:
[REACTION:BLACK_BRONZE_MAKING]
[NAME:make black bronze bars]
[BUILDING:SMELTER:NONE]
This indicates the building necessary to perform this reaction. The third bit, null here, is the hotkey for setting this task at the building.
[REAGENT:A:300:BAR:NO_SUBTYPE:METAL:COPPER]
[REAGENT:B:150:BAR:NO_SUBTYPE:METAL:SILVER]
[REAGENT:C:150:BAR:NO_SUBTYPE:METAL:GOLD]
These are the ingredients necessary. The ABC stuff is clearly to differentiate between reagents, because a specific reagent sometimes needs to be referenced (such as with the GET_MATERIAL_FROM_REAGENT thing).
The third bit seems to be the amount necessary. I've noticed that with most objects, this is in single units. With bars, it's a multiple of 150, and with thread it's like 15000. From this, I'm inferring that a bar is broken down into 150 reactive units, and thread into 15000. By this logic, this reaction uses two bars of copper, and one bar each of silver and gold. Am I right? If so, how far does this go? Can I make a reaction that uses only half of a bar by inputting "75" for that argument? Also, what happens to the rest of a partially-used bar? Does the game remember that it's only half a bar now?
The fourth argument is, again, item type. Again, I'm wondering what types are understood by the software. Does WEAPON work? CRAFT? What about, I dunno, BRACELET?
From there, the arguments seem to be about narrowing down the item. METAL indicates that this isn't just a bar, but a metal bar, then it goes further to specify which metals. As for "NO_SUBTYPE," I got no clue what to make of that because I couldn't find anything that had a different value for that argument, aside from "NONE." I'm guessing that NO_SUBTYPE is different from NONE in some way.
[PRODUCT:100:4:BAR:NO_SUBTYPE:METAL:BLACK_BRONZE][PRODUCT_DIMENSION:150]
This line indicates the product of this reaction. That second argument, "100," had me stumped for a while, but I think I've got it. It's the probability of this product being produced, yes? I know there is at least one reaction (smelting tetrahydrite) that has only a 20% chance of producing a given product, so it stands to reason that there must be a method for setting such probabilities. "4" is the number of this product yielded.
"PRODUCT_DIMENSION:150" had me stumped for a while, but that's just how the game knows that this product (a bar) has 150 reactive units, yes? And a standard thread product would have a dimension of 15000?
[FUEL]
[SKILL:SMELT]
These are obvious. This reaction requires fuel, and uses the smelting (or "furnace operating," right?) skill. What are the valid entries for the skill argument? For instance, is it "MECHANIC" or "MECHANICS"? Can I add skills? If so, what file do they need to be in?
Let's look at another reaction that's got something I don't get: steel making.
[REACTION:STEEL_MAKING]
[NAME:make steel bars]
[BUILDING:SMELTER:NONE]
[REAGENT:A:150:BAR:NO_SUBTYPE:METAL:IRON]
[REAGENT:B:150:BAR:NO_SUBTYPE:METAL:PIG_IRON]
[REAGENT:C:1:BOULDER:NO_SUBTYPE:NONE:NONE][REACTION_CLASS:FLUX]
I get it up through here. [REACTION_CLASS:FLUX] just means that this boulder has to be a flux stone. But it's got me wondering, what other reaction classes are there? I know there's gypsum. What else? Can I make my own? If so, where do they go?
[REAGENT:D:150:BAR:NO_SUBTYPE:COAL:NO_MATGLOSS]
Here's where it loses me. Now, I know that this isn't the same as the fuel tag below. Because, otherwise, this would be redundant. Also because my random knowledge database tells me that Iron Age steel was a variety of carbon steel made by layering strips of iron, coal, and strips of pig iron, then heating them and hammering & folding the crap out of them; this mixes the two metals all up together with the carbon from the coal, which (for some reason unknown to me because I'm not a metallurgist) makes the metal more flexible and way more durable. So that's not what confuses me. It's the "NO_MATGLOSS." "MAT" must be short for "material." I'm gathering that this means that it doesn't matter whether it's charcoal or coke, but why is it necessary to say "NO_MATGLOSS" instead of "NONE"? What am I missing?
[PRODUCT:100:2:BAR:NO_SUBTYPE:METAL:STEEL][PRODUCT_DIMENSION:150]
[FUEL]
[SKILL:SMELT]
This stuff I get, as I said.
Now, before I go any further with exploring the syntax, I want to make sure that I'm understanding all these correctly. Don't want to forge (bu-dum-splish) onward based on erroneous conclusions. So, clue me in, correct me, and so on and so forth.