Installation instructions:

1. Copy the files into your raw/objects folder.

2. Add the following to the civilisation you have set as playable in entity_default.txt:

[PERMITTED_BUILDING:GUN_FORGE]
[PERMITTED_BUILDING:BULLET_MINT]
[PERMITTED_BUILDING:WORK_BENCH]

[PERMITTED_REACTION:FIRELOCK_L]
[PERMITTED_REACTION:FIRELOCK_S]
[PERMITTED_REACTION:SPRINGLOCK_L]
[PERMITTED_REACTION:SPRINGLOCK_S]

[PERMITTED_REACTION:UNBOX1]
[PERMITTED_REACTION:UNBOX2]
[PERMITTED_REACTION:UNBOX3]
[PERMITTED_REACTION:UNBOX4]

[PERMITTED_REACTION:MAKE_BPOWDER_P]
[PERMITTED_REACTION:MAKE_BPOWDER_S]

[PERMITTED_REACTION:CARTRIDGES_L]
[PERMITTED_REACTION:CARTRIDGES_S]
[PERMITTED_REACTION:CARTRIDGES_B]

[PERMITTED_REACTION:LEAD_BULLET_L]
[PERMITTED_REACTION:IRON_BULLET_L]
[PERMITTED_REACTION:COPPER_BULLET_L]
[PERMITTED_REACTION:ANY_BULLET_L]
[PERMITTED_REACTION:LEAD_BULLET_S]
[PERMITTED_REACTION:IRON_BULLET_S]
[PERMITTED_REACTION:COPPER_BULLET_S]
[PERMITTED_REACTION:ANY_BULLET_S]

[PERMITTED_REACTION:IRON_ROCKET]
[PERMITTED_REACTION:STEEL_ROCKET]
[PERMITTED_REACTION:COPPER_ROCKET]
[PERMITTED_REACTION:WOOD_ROCKET]

[PERMITTED_REACTION:IRON_MUSKET]
[PERMITTED_REACTION:BRONZE_MUSKET]
[PERMITTED_REACTION:STEEL_MUSKET]
[PERMITTED_REACTION:IRON_RIFLE]
[PERMITTED_REACTION:BRONZE_RIFLE]
[PERMITTED_REACTION:STEEL_RIFLE]
[PERMITTED_REACTION:IRON_PISTOL]
[PERMITTED_REACTION:BRONZE_PISTOL]
[PERMITTED_REACTION:STEEL_PISTOL_BLADED]
[PERMITTED_REACTION:IRON_PISTOL_BLADED]
[PERMITTED_REACTION:BRONZE_PISTOL_BLADED]
[PERMITTED_REACTION:STEEL_PISTOL_BLADED]
[PERMITTED_REACTION:COPPER_AIRGUN]
[PERMITTED_REACTION:IRON_AIRGUN]
[PERMITTED_REACTION:BRONZE_AIRGUN]
[PERMITTED_REACTION:STEEL_BBGUN]
[PERMITTED_REACTION:COPPER_BBGUN]
[PERMITTED_REACTION:IRON_BBGUN]
[PERMITTED_REACTION:BRONZE_BBGUN]
[PERMITTED_REACTION:STEEL_BBGUN]
[PERMITTED_REACTION:IRON_CARBINE]
[PERMITTED_REACTION:BRONZE_CARBINE]
[PERMITTED_REACTION:STEEL_CARBINE]
[PERMITTED_REACTION:IRON_SHOTGUN]
[PERMITTED_REACTION:BRONZE_SHOTGUN]
[PERMITTED_REACTION:STEEL_SHOTGUN]
[PERMITTED_REACTION:ROCKET_TUBE]

3. Add some combination of the following to any other civs you want to be armed with guns, and/or buy components from.

[ITEM_WEAPON:ITEM_WEAPON_MUSKET]
[ITEM_WEAPON:ITEM_WEAPON_RIFLE]
[ITEM_AMMO:ITEM_AMMO_CARTRIDGE_L]a

[ITEM_WEAPON:ITEM_WEAPON_AIRGUN]
[ITEM_AMMO:ITEM_AMMO_BULLET_L]

[ITEM_WEAPON:ITEM_WEAPON_BBGUN]
[ITEM_AMMO:ITEM_AMMO_BULLET_S]

[ITEM_WEAPON:ITEM_WEAPON_PISTOL]
[ITEM_WEAPON:ITEM_WEAPON_PISTOL_BLADED]
[ITEM:WEAPON:ITEM_WEAPON_CARBINE]
[ITEM_AMMO:ITEM_AMMO_CARTRIDGE_S]a

[ITEM_WEAPON:ITEM_WEAPON_ROCKET]
[ITEM_AMMO:ITEM_AMMO_ROCKET]

[ITEM_WEAPON:ITEM_WEAPON_SHOTGUN]
[ITEM_WEAPON:ITEM_WEAPON_SHOTGUN_SAWN_OFF]
[ITEM_AMMO:ITEM_AMMO_BUCKSHOT]

[PERMITTED_REACTION:MAKE_BPOWDER_P]
[PERMITTED_REACTION:MAKE_BPOWDER_S]

[ITEM_TOOL:ITEM_TOOL_BOX_FL_L]b
[ITEM_TOOL:ITEM_TOOL_BOX_FL_S]b
[ITEM_TOOL:ITEM_TOOL_BOX_SL_L]b
[ITEM_TOOL:ITEM_TOOL_BOX_SL_S]b

a. You only need one entry for ammunition if you have more than one weapon that fires the same sort.
b. These are to simplify the process of importing firelocks and spring-locks to maps with no easy access to steel. Please don't use them as an exploit.

______________________________________________________________________________________

How To Use:

First, a note of caution: This mod does not make bows and crossbows redundant. Getting a firearms industry working is time-consuming and complicated and you'll almost certainly not find all the raw materials you need on one map, so expect to buy a lot of stuff from the caravans.

There are two main processes involved, making the weapons and making the ammunition. All but one of the necessary reactions involved go on within the three dedicated firearms workshops, meaning that you can put in a work-order for a load of the necessary components and then forget about it while your craftsdwarf's shops, metalsmith's forges and other workshops are unmolested. The exception is gunpowder, which you'll probably only be making intermittently.

To make a gun, you need metal bars, wood and either firelocks or spring-locks. (Barrels, stocks etc are not yet modelled.) The required materials are as follows:

Rifle, Musket, Hand mortar, Shotgun 1 metal bar 1 Large firelock 1 log
Spring-gun 1 metal bar* 1 Large spring-lock 1 Log
Pistol, Bladed pistol, Carbine 0.5 metal bars 1 Small firelock 1 Log
Small spring-gun 0.5 metal bars* 1 Small spring-lock 1 Log

* These weapons can be made out of copper. All others are restricted to iron, bronze or steel.

Note that since DF isn't really set up for using partial metal bars, pistols, carbines and small spring-guns are made in pairs. All these weapons are assembled in the Gunsmith's Forge using Weaponsmithing. The Gunsmith's forge is also where firelocks and spring-locks are made, using Metalcrafting. These can only be made from steel, but one steel bar will create six large or ten small locks of either type.

Firelocks and spring-locks can be bought from the caravans in boxes, which can be opened at the Workbench using the Striking skill. There's a 95% chance you'll get a wooden chest free out of this reaction, but occasionally it'll break. Each box contains six large or ten small locks of the type you bought.

Ammunition is a two-step process, at least for gunpowder arms. The first step is to make a batch of gunstones at the Ammunition Mint, using the Metalcrafting labour. These can be made of quite literally any metal, although there are separate reactions for lead, iron and copper. You are strongly advised to set the Ammunition Mint to take from a specific stockpile that accepts only the metals you want made into ammunition if you use the "Make small/large gunstones from any metal". Either way, you get sixty large or one hundred small gunstones from each bar.

The best metal for ammunition is... Well, whatever you've got, really. Shot made from lead or other mostly-useless metals like tin or zinc will reliably kill or incapacitate through leather, and do significant harm through chain mail; plate armour might give a bit more trouble, but it conveniently leaves the shoulders and upper arms vulnerable so your thin bearded line will only have to get lucky once. Iron and copper bullets are even better.

Gunstones can be fired from spring guns by themselves, but if you want a bit more bang for your dwarfbuck you'll need to combine them with some cloth and a sack of gunpowder at the Workbench with the Clothesmaking skill. (This is a placeholder until paper is implemented in Fortress Mode.) The ratios are as follows:

1 stack of 60 large gunstones 1 stack of 60 large cartridges
1 stack of 100 small gunstones 1 stack of 100 large cartridges
3 stacks of 100 small gunstones 1 stack of 50 buckshot cartridges

Last of all we have rockets for the hand mortar, which are a slight oddball among the ammunition types. Metal ones are made at the Gunsmith's Forge, wooden ones at the Workbench, with the gunpowder added directly. You only get five per log or bar, but if you need to fire more than five of these at one opponent you're having serious Fun.

As for gunpowder itself, you will require the following: 2 blocks of coal or charcoal, 8 blocks of saltpeter or potash, 1 boulder of brimstone and ten empty bags. This is the only BPFA reaction to take place at the Smelter, using furnace operating; if you have another mod installed that uses the Alchemy skill for something then you may wish to modify the raws accordingly. The Dwarf Chocolate Plugin version of this mod (currently defunct pending DC updating to v0.40) uses the Alchemy skill at the Alchemist's Workshop.

As you will have noticed, gunpowder is a very resource-intensive item to make on-site. Expect to end up buying a lot of it from the caravans, along with ready-made ammunition, and use what you do buy with great care.

As to which firearms are the best? That's largely a matter for opinion. Rifles and muskets are the most powerful conventional firearms, but pistols weigh the least and can be used in conjunction with a shield, and carbines are somewhere in the middle. Spring-guns are significantly less powerful, only a moderate improvement over crossbows, but their ammunition is faster to make and requires no gunpowder. Shotguns are brutally effective for pulping or severing body parts but of very limited use against armour. Hand mortars can reliably incapacitate anything up to some megabeasts, but their ammunition is fearsomely expensive.

______________________________________________________________________________________

Known (or suspected) issues:

Weapons and ammunition only obtainable through reactions don't turn up with caravans, or presumably in the hands of invaders. The only known workaround for this is to add them to entity_default as [WEAPON:ITEM_WEAPON_MUSKET] etc.

Bullets might occasionally be found stuck in the ground or dead enemies the way arrows or crossbow bolts are, although arena testing suggests that this is quite rare. Material and velocity apparently plays some part in determining how often this happens, but there's not much !!SCIENCE!! on the subject.

Guns fitted with bayonets can be fitted to upright spear traps, which I suppose is as good a way as any of using up weapons that are surplus to requirements. Guns can also be added to weapon traps and function quite normally, which makes very little sense but can't be helped.

"Individual choice, ranged" creates issues with dwarves picking up the wrong kind of ammunition, which is a known bug in vanilla. I'm not yet certain how this affects hunters, but if you want to use gunstones for training and cartridges for combat, the only method I'm aware of is to set up a separate 'trainee' squad.

______________________________________________________________________________________

Acknowledgements:

Toady One and ThreeToe for creating this wonderful platform for our individual and collective creativity.

Michael_Almeida for letting me use his Muskets mod as the basis for the first version of BPFA.

Hugo the Dwarf, Fredd, Acperience, Meph and many others for their invaluable advice and support.

Everyone who's built on my work to enhance their own mods, mentioned me in their sig or just posted in the thread with a kind word.