I've always thought I'd work on this bit by bit in drafts then publish the whole thing finished, complete. However, that has lead me to think this guide may not be so useful and so, I've never quite finished...
So instead, I've just had the idea to make this public: publish this guide as a Work-In-Progress. In part it's to make edits easier, but more so that this knowledge is out there, in case anybody needs it. I'll be making constant edits in the coming days, here's what I've got so far.
--------------------------------------------------
Post last updated 11/27/2018
--------------------------------------------------
Thought I'd update part 1 of Metzelmax's old guide (viewtopic.php?f=12&t=17122) for AE as well as what is and isn't essential, for all the 5 weapon types. I'll be including a section on drones since they are related, and parts of the guide will have examples of using slipstream mod commands.
I'm not going to cover the animation and audio bits again in full detail... Metzelmax's guide does a pretty good job of that.
This will be in the same style as their guide and includes portions of it too, as MetzelMax got a lot of it right. I won't directly quote Metzelmax all the time, especially sections I correct for better wording, but know their words are there.
Intro and Setup
What is an '.ftl' file? An '.ftl' file is actually just a '.zip' file (a compressed zipped folder) renamed, so that it can be differentiated from '.zip'. Placing '.ftl' files inside Slipstream Mod Manager's 'mods' folder lets you use them.
This guide will go over creating an '.ftl' file, and show how the folders are set up inside it.
Thus Slipstream Mod Manager and '.ftl' files are used.Metzelmax wrote:You can just simply mod the existing XML's in the game, but that would mean you would have to reinstall to get rid of the modded stuff.
The current version of Slipstream Mod Manager (v1.9.1) can create a mod boilerplate for you. Just use "File -> New Mod..."
The directory name should be whatever you end up calling the mod file, as when you create the mod (select all the folders, add to .zip archive), the .zip will take the folder's name.
Since we're making a weapon, you'll need the 'data' folder for sure. Add the 'img' folder if you plan to spice up your weapon with some custom art, and the 'audio' folder if you plan on adding a custom sound effect. The rest of the fields below are relevant to the description of the mod when browsing mods in Slipstream. Once you click "Generate Mod", you should be presented with some folders:
data - inside create a text file called blueprints.xml.append. we'll be working in this file.
(if you plan on adding custom sounds) audio - just look at "III Sound" in Metzelmax's original guide
(if you plan on adding custom art) img - inside create a folder called 'weapons', then look at "II The Visuals" in Metzelmax's original guide. the 'weapons' sub-folder is technically not necessary, but is what vanilla does so you should do it too! for organization reasons really.
mod-appendix - inside here is the metadata.xml, which is in charge of the Slipstream description. if you kept the XML Comments box checked, there should be comments here to help you better understand the meaning of all the different fields.
The Code
Familiarity with XML is recommended, but I did learn XML from modding FTLMetzelmax wrote:You will only be using XML language to change values within some predetermined tags.
I'm not going to do a tutorial on XML syntax, but there are resources out there.or you can use slipstream tags to overwrite an existing weapon or other thing, not always neccesary, but are quite versatile. I'll get back to this later.Metzelmax wrote:Every weapon you make must be within a weaponBlueprint tag. This tag contains the name of the weapon which is its unique id. If you create 2 weapons with the same name the game will pick the weapon located the furthest down the xml file. You can use this to overwrite existing weapons in the game.
A rundown of which tags every weapon, regardless of type, must use
Code: Select all
<weaponBlueprint name="MY_WEAPON_NAME">
All the stats/tags of a weapon must be within this tag and its respective closing tag. The name attribute gives a name by which to reference the weapon by in the code. By convention, the value of this attribute is in uppercase (easy to see), underscores (makes double-clicking select the whole name) are used to show spaces between words, and numbers can be used.
<type>BURST</type>
The value of this tag can be one of 5: BEAM, LASER, MISSILES, BOMB, or BURST. each type has its own mandatory tags and possible tags, though there is some overlap there. I'll be covering the differences in detail.
<title>Flak Gun Mark I</text>
The title of the weapon as seen in-game at the top of the description UI box, as when hovering over a weapon in the hangar, the equipment screen, or a store. Don't make this too long, otherwise it will go beyond the boundary of the box.
<short>Flak I</short>
The shorter form of the weapon's title, as seen in-game in the hangar when looking at a weapon without hovering over it with the mouse. This short form is also what you see in the weapons system's box on the main gameplay screen.
<desc>If given enough time to prepare, the 'Swarm' missile launcher can replicate multiple warheads.</desc>
A description of the weapon as seen in the description UI box, as when hovering over a weapon in the hangar, the equipment screen, or a store. The weapon stats+description box has a fixed size, so don't make the description too long. You can add line breaks as well for paragraphs, but you'll generally not want to do that because of just how limited space there is.
How much space for the description you have depends on how many stats the weapon has. You'll want to test and see just how much space that is so that your description doesn't cause the stats to flow out of the box, which not only does not look good, but can have ill effects if the weapon has a <tip> tag. If you really want to go more in-depth about your weapon... perhaps strategy or lore or anything else, you can add it to the <tip> box, which is great because its size changes depending on how much info is inside.
If the weapon is intended for use in an artillery system, then the description will go into the description for the artillery when hovered over in the hangar or the upgrades screen.
<tooltip>Artillery: Flak gun that automatically fires 7 projectiles</tooltip>
This tag is only mandatory for weapons intended for use in an artillery system. Should be left out for weapons not intended for use as artillery.
For regular weapons, this tag used to give you a description of a weapon's stats when hovering over a weapon in the weapons system tray on the main gameplay screen. However, it was made obsolete by the current design, which derives a weapon's stats... directly from its stats -- you see it listed as Shots Per Charge, Normal Damage, System Damage, Possible Effect, etc.
When hovering over the artillery system on the main gameplay screen, no such derived listing is found. This is where <tooltip> comes into play: it should be a description of the artillery weapon's stats. For gameplay purposes, it should be as detailed as possible, but the level of detail is left up to you.
<cooldown>15.5</cooldown>
Declares the cooldown, how long a weapon takes to recharge, in seconds. Decimal places can be used, e.g. 15.666, but should only be used if necessary, and should be limited to 1-2 places max. In most places, you won't see any decimal places since they can confuse the player.
When set below 0, the weapon will not fire, and I would guess the same would happen if set at 0.
<power>2</power>
Declares the power cost of a weapon. this should be a number from 1-4, emphasis on should. 5 power cost is rarely a good idea, the only good example I can think of was in Gencool's ArwingAdventures mod, where one weapon was continuously upgraded, and 5 power was the final upgrade or something.
The power cost can be set to 0, in which case the weapon will need another weapon powered in order to fire.
- when done with a weapon that decreases in cooldown to a negative value, the weapon will have a limited number of uses, and cannot be depowered.
- there is an exploit that can be done here, sort of. the weapon will still "fire" if depowered and will continue to reload, though nothing will come out. when done several times and then finally repowered, the weapon will fire at ALL of its targets starting from the most recent target.
The power cost can also be set below 0, which is just as described above, but the weapon will also provide that much power to the weapons right of it in the weapons system. See Gencool's Skimmers for examples (he discovered this!).
<cost>45</cost>
The price of the weapon when seen in the store. The sell price of the weapon is the cost divided by 2, rounded down, which is useful to figure out if the weapon is made unobtainable (rarity of 0). In this case, the sell price is 22.
<rarity>2</rarity>
0 rarity means the weapon is unobtainable. this can be useful for custom ship weaponry, enemy weaponry, or if you want to make weapons available only in certain sectors (done in the sectorDescription tag of a sector)
rarity is configured in a pool of weapons, as follows (shoutout to slowriderxcorps figuring this out):
1 rarity means the weapon is given 5 entries into the loot pool.
2 rarity means the weapon is given 4 entries into the loot pool.
3 rarity means the weapon is given 3 entries into the loot pool.
4 rarity means the weapon is given 2 entries into the loot pool.
5 rarity means the weapon is given 1 entry into the loot pool.
you can similarly change the rarity of a weapon to make it rarer or more common in certain sectors (done in the sectorDescription tag of a sector)
<weaponArt>burst_laser_1</weaponArt>
This tag is responsible for what the weapon looks like in-game. The value for this tag will be the name of this weapon's corresponding weaponAnim tag in the animation data. See Metzelmax's guide on animation for more details.
<launchSounds>
<sound>my_launch_sound</sound>
<sound>sounds_are_cool</sound>
</launchSounds>
Lists of <sound> tags that play when the weapon fires. The value of each <sound> tag is a sound found in the sounds data, and can be called anything. See Metzelmax's guide on sounds for more details.
A rundown of which tags every weapon, regardless of type, can use (optional)
Code: Select all
<flavorType>Physical Projectile</flavorType>
This small tidbit of information is seen at the top of the tooltip box that displays when you hover over a weapon on the main gameplay screen, usually denoting what the weapon's projectile is.
But it can be anything, and as long as you want. You can make it into a full sentence or more, add line breaks, etc. While it was originally meant for a bit of flavor, you can put in the full description of the weapon, making it visible even in combat! Just remember that this was never intended, and most if not all players expect quick information from the box. But I still love that this is possible!
<tip>tip_beams</tip>
Using this tag with a valid value, the name of a <text> in text_misc.xml, gives a weapon a tip box underneath the stats+desc box found in stores and in the equipment screen (not found in the hangar). The tip box will always show in stores, but there's a bug that makes it not always show for weapon slots in the equipment screen. The tip box usually shows an extremely general tip about the weapon which is sometimes very obvious, like how lasers work.
However, you can also briefly discuss strategy or lore if you want -- the tip box will resize itself to fit, unlike the stats+description box. If you want to create line breaks (for paragraphs and the like) I believe you need to use the newline character \n.
<ion>2</ion>
Declares how much ion damage a weapon does. I'm not going to go into how ion damage works since you probably already know. Setting negative values shouldn't do anything. You can set the value to 0, but at that point you might as well just not include it.
<damage>1</damage>
Declares how much regular damage the weapon will do. Each point of damage here is a point in hull damage, system damage, and 15 crew damage. Can be any integer value, though setting it to something extreme may screw with the game. You can set the value to 0, but at that point you might as well just not include it. Values less than 0 will repair hull damage and negate damage from the sysDamage or persDamage tags if they are included and greater than 0.
<sysDamage>2</sysDamage>
Each point of sysDamage gives, you guessed it, a point of system damage. Can be any integer value, though setting it to something extreme may screw with the game. You can set the value to 0, but at that point you might as well just not include it. Values less than 0 can be used to either negate points from <damage> or repair systems.
<persDamage>3</persDamage>
Each point of persDamage gives the weapon 15 crew damage. Can be any integer value, though setting it to something extreme may screw with the game. You can set the value to 0, but at that point you might as well just not include it. Values less than 0 only heal crew when the weapon is of type BOMB, but can be used to negate crew damage points from <damage>.
<fireChance>7</fireChance>
Gives the weapon a chance to start a fire whenever it hits, with a value from 1-10, 1 being a 10% chance and 10 being a 100% chance. You can set the value to 0, but at that point you might as well just not include it.
<breachChance>3</breachChance>
Gives the weapon a chance to cause a hull breach whenever it hits, with a value from 1-10. You can set the value to 0, but at that point you might as well just not include it.
A somewhat recent discovery found that a breach roll happens only after an unsuccessful fire roll, and therefore the true chance is not 10% to 100% if fire chance is greater than 0. The formula for the true breach chance is
(10 - <fireChance>) times (<breachChance>).
For example, if the fireChance is 3 and the breachChance is 4, the true breach chance is not 40%, but rather 28%.
<stunChance>2</stunChance>
Gives the weapon a chance to stun for 3 seconds, with a value from 1-10, 1 being a 10% chance and 10 being a 100% chance. You can set the value to 0, but at that point you might as well just not include it.
<stun>7</stun>
Gives the weapon a guaranteed stun, the value being the number of seconds. You can set the value to 0, but at that point you might as well just not include it.
<hullBust>1</hullBust>
Grants the weapon the ability to do double hull damage on each systemless room the weapon hits. You can set the value to 0, but at that point you might as well just not include it.
<boost>
see gentasaurus's tutorial, Weapon Boost Effect, on how this tag is used as it does a pretty good job at explaining.and a link to gentasaurus's tutorial, Weapon Boost Effect, viewtopic.php?f=12&t=29812
A rundown of which tags certain weapons must use, in addition to the mandatory tags above.
Code: Select all
<shots>3</shots> {LASER, MISSILES, BURST, BOMB}
The number of shots a weapon fires. Note that 2 shots on a BURST type weapon doubles all the resulting projectiles in the <projectiles> tag.
<sp>0</sp> {BEAM, LASER, MISSILES, BURST}
Declares how much shield piercing the weapon has.
A non-BEAM weapon with shield piercing 1 or greater that deals 0 <damage> and 0 <ion> will be able to pass through zoltan shields and not damage them at all, like a weapon that only deals system damage.
A negative value only has meaning for BEAM weapons with <damage> greater than 1, that is, the reduced damage through shields of such beams does that much less damage. Let's think about it with an example. A 3 <damage> beam would normally do -1 damage for each shield: 1 shield is 2 damage, 2 shields is 1 damage, 3 shields and up is 0 damage. Adding -1 <sp> to this beam causes it to do 1 less damage through shields: 1 shield is now 1 damage, 2 shields and up is 0 damage.
A BEAM weapon with 0 <damage> will require 1 extra point to <sp> than you may think. For example, for 0 <damage> beam to pierce 2 shields, it will need 3 <sp>, not 2.
<length>145</length> {BEAM}
Declares how long, in pixels, the beam's trail/span is. Value can be a decimal number, but a 0.1 <length> may not be visible when targeted.
For comparison, the mini beam length is 45, the glaive beam is 80, the pike beam is 170, the hull beam is 100, and the fire and anti-bio beams are both 140.
<image>laser_heavy1</image> {LASER, MISSILES}
The projectile the weapon fires. Refers to an anim in the animations data which contains the image location.
<image>beam_contact</image> {BEAM}
The contact image the beam makes when it hits the enemy ship or shields. Refers to an anim in the animations data which contains the image location.
<image>bomb1</image> {BOMB}
The animation of the bomb appearing on the enemy ship (or empty space when missing) right before it explodes. For bombs, the projectiles teleport directly onto the enemy (or player) ship, never seen in between the two ships.
<missiles>2</missiles> {MISSILES}
Specifies how many missiles a missile weapon uses up each time it fires.
A rundown of optional tags certain weapons can have
Code: Select all
<lockdown>1</lockdown> {LASER, MISSILES, BURST, BOMB}
Gives the weapon a crystal lockdown effect on each room the weapon hits. You can set the value to 0, but at that point you might as well just not include it.
<speed>7</speed> {BEAM, LASER, MISSILES, BURST}
How fast the weapon's "projectile" is after it is fired. For beams this means how fast the span of its beam goes through its length. If you know the slow Scythe beams of CE, you'll know this can make all the difference. As for the other weapons, you know how much of a difference it makes between the shot speed of Burst Lasers, Charge Lasers, and the Flaks. What exactly a value of <speed> means differs for each of these types, as can be seen by their default values:
BEAM default is 5
LASER default is 60
MISSILES and BURST default is 35
~~~more to be added~~~
Examples to be added here...
Discuss differences in drones here...
This guide ain't done yet!
