Making Mods for FTL

Finished the game and want more? Can't find a mod that suits your fancy? Then make your own! This guide will get you set with the tools, then the rest is up to you!

Filling Your Toolbox.

Most of the tools you need you've already got. You have a computer connected to the internet, you have the game, what more do you need? Well, not much more than the Slipstream Mod Manager[www.subsetgames.com] and a text editor of your choice that can handle .xml files. My preference would be for Notepad++[notepad-plus-plus.org] as it denotes the lines and makes it easier to navigate to any trouble spots you may have in your code.

With these two tools in hand, you're practically set. The only other tool you may want is software to unzip files, that way you might examine other users' mods to learn how they did something, and for that, my suggestion would be to use 7zip.[www.7-zip.org] In addition, if you want to modify the appearance of weapons or build your own custom ships, you may want image-editing software, for which I also have a recommendation, that being GIMP[www.gimp.org].

All that being said, you only really need the first two tools to do the bulk of any mod creation that doesn't involve custom assets (new drones/weapons/ships/backgrounds/etc.).

Additional Tools:

• Modding Test Environment.[www.subsetgames.com]
  
• Error Checker.[www.subsetgames.com]
  
• Superluminal Ship Editor.[www.subsetgames.com]
  
• Alternate Hull Strength HUD.[www.subsetgames.com]

Unpacking the Game with Slipstream.

Once you've your toolbox at hand, you may want to dive right in, but first you need to know how to get at those rich .xmls. To access FTL's xml files, you'll need to use the aforementioned mod manager to extract them from the .dat in the root folder wherever you've installed FTL.

Typically this would be, for Windows users either:
C:\Program Files (x86)\Steam\steamapps\common\FTL\
C:\GOG Games\FTL\

For Mac users:
/Applications/FTL.app/Contents/

For Linux users:
~/.local/share/Steam/SteamApps/common/FTL Faster Than Light/data/

More specifically, how to do this with the mod manager is to go where you installed it, click modmanager.exe and configure your file path to the right spot (one of the above, or your custom install location). Once that's done, it's as simple as going to File and Extract .dats, then choosing where to have them extracted. This will output everything from the .dat file, but you'll probably be most interested in the data folder, as that's where the most valuable stuff is to work with, unless your aim is more towards making custom assets. In which case, you'll probably be more interested in the images folder.

(Note: in older versions of the game, there was a resources folder that contained multiple .dat files to extract from. Since then, these have been consolidated and moved to the main folder for the game. I haven't messed with modding this game since the Advanced Edition update came along and so hadn't realized this until, well, just this year. Apologies for any confusion that may have arisen as a result.)

Appending is everything

Now that you've got access to many of the core elements of the game, you still probably won't know exactly what to do with them all. Well, the first thing to note is that you don't want to mess with any of this stuff, for the most part. The reason you've unpacked them is for an easy look at how they're named and how their contents are written, more than anything else.

Any adjustments you want to make to the specific files may be made in them, but it's much safer to instead append them in a separate, copied file instead or better yet, an entirely new file. This way you retain the original, and avoid overwriting and potentially breaking your users' games, in the event you botched something or it conflicts with someone else's mod. Which is itself the other reason you always want to make up your mod mostly out of append files, this keeps the core files intact, and ideally avoids mod conflicts.

That being said, if you're not making direct adjustments to the core .xml files, as in the creation of a new ship, you may include those in your mod as plain .xml/.txt files. Albeit, you'll need to append the blueprints to be aware of their existence.

Append append append, what do I mean by that? Well, the basic files of the game in the data folder are all .xml. When you open them to edit or read them, they remain that way, but if you change anything you'll want to save it with the original filename, but .append added after .xml.

Otherwise, those changes are saved to the original file, which for the aforementioned reasons, you do not want. However, to avoid this potential problem from incidental saving without changing the file extension, you may create an entirely new file as mentioned above with your desired changes. All you need to do then is remember to give it the same name as the file the changes are being appended to, as in the example below.

E.g. blueprint.xml.append

This may be the original file, simply with your changes written in it somewhere and the file extension changed, or it may be, in a much cleaner and more easily managed way, a new, distinct file with your changes written in it.

To recap, don't change the .xmls found in the data folder, use them as reference for names and content structure, then make new, separate .xml.append files in another folder with the names of the files you want to alter, and build up from there. This way you'll avoid breaking your game, your users' games, and other mods.

Packaging is sensitive to file structure

By now, you may already be miles ahead learning the content structure of the .xml files and filling up a folder with all manner of .xml.append files ready to pack up and release as a mod. However, you might not yet know how exactly they need to be arranged to be accepted by FTL. This is a pretty straightforward task, but easy to miss or mix up if you're not very organized with your files.

FTL will only accept mods packed in exactly the same way as they're found in the unpacked folders. So, for example, any .xml.append files must be placed in a folder named data, any edited images must be placed in a folder named img (and whichever subfolder it may have come from, if it did).

Nevertheless, these folders themselves may be placed in a folder of your naming, without issue. So data and img may be in a folder named SPIDERS ARE PEOPLE TOO, or whatever you choose to name your mod, and this will be a-okay. Alongside this, outside of the data and img folders you may want to create another folder named mod-appendix and copy over Slipstream's default metadata.xml files (which may be found in the sample mods provided, i.e. Beginning Scrap Advantage/Engi Scrap Advantage) into the folder and adjust it for your mod, as this will provide information as to what your mod is within Slipstream itself, making it easier for those that choose to run with many mods to keep track of what exactly each mod is.

Once you've got everything in the right places, you merely need to zip up your mod, and change the file extension to .ftl. To do all of this, under Windows you right click and either send to compressed folder or 7zip -> add to [filename].zip. To access the file extensions, you'll want to hit alt within the explorer window* and go to Tools->Folder Options->View->untick the box next to Hide Extensions for Known Filetypes**. Then you'll be able to see .zip and readjust it to .ftl.

If you would prefer to avoid having to readjust the extension, however, you may also go into Slipstream's preferences via File->Settings and tick the box for allowing .zip files, but since its default is set to .ftl, it may be easier to simply adjust your extension instead of hoping others have adjusted their Slipstream settings.

*(Minor pro tip, to avoid having to hit alt to bring up the menu bar each time, if you select organize in the explorer window and go to layout, you may enable the menu bar by default.)
**(Additional protip, for almost any version of Windows or recent versions of Mac OS X, you may find instructions on how to reveal file extensions here[www.granneman.com] and for Mac users of Moutain Lion[support.apple.com] or Mavericks here[support.apple.com].)

To recap, once your mod's done, you'll want to do the following:
Place all your files within the appropriate folders within your main mod folder. So:

[Mod folder name, e.g. Spiders are people too]
-mod-appendix
-data
-img
--ship
--etc.

Ensure all files within the data folder that affect the core .xml files are .xml.append.
Zip up the mod folder and change the file extension to .ftl for ease of use with Slipstream for others.

Upload the mod to your trusted file host and shoot the link out to others to let them try out your mod from there!

That's all folks!

Hope this helps anyone that's been interested in modding FTL, but didn't want to wade through various tutorials for some of the very basics. However, I would still heavily recommend visiting the FTL mod development forum[www.ftlgame.com] for more detailed information on anything I've not touched on here (such as more specific areas of modding like event structuring/making custom assets like ships/weapons/drones/etc.).

This guide's only intent was to get you to the basic tools for accessing the game's core content for manipulation, explain what not to do in the process of manipulation, and once you've learned how to rework them, how to compile them to be patched into the game for use.

I hope this has fulfilled that intent adequately and is of use to anyone interested in adding their own unique content to FTL. For any further help or direction, feel free to comment on this (or post in any of the linked threads below) or go ask more experienced users over on the FTL mod development forums. They're all very welcoming and helpful to newcomers, as long as you can provide sufficient information to help frame your inquiry. =)

P.S. My advice: backup everything. In fact, copy your FTL folder, rename it, make that your dedicated mod testing grounds. That way you can go back to playing it whenever while you hash out your mod in the other copy. Much easier than deleting and reinstalling if you find you've cornered yourself into a completely dysfunctional install somehow.

Additional helpful links.

• Modding Guide[ftlwiki.com]
  
• Ship file content structure[ftlwiki.com]
  
• Events file structure[ftlwiki.com]
  
• Captain Shooby's mod tutorial (event & sector creation/configuration).[docs.google.com]
  
• Modding reference links, for everything I didn't cover above.[www.ftlgame.com]

Discussion threads (if you come across this on the greater web):

• On Steam.
  
• On GOG.[www.gog.com]
  
• On FTL official forums.[www.ftlgame.com]
  
• On Reddit.

[Gmr Leon]

Funk, I think you may have misunderstood what the extract dats function is doing. It's not requesting you locate the .dats file, it's asking which directory you would like the contents of the .dat file to be extracted to. Think of it like unzipping a file, and how it asks where you'd like the unzipped contents to be placed.

Simply create a directory/folder (right click, new folder) to place the resources extracted from ftl.dat into and you should be good. Sorry for the confusion, reviewing how I wrote that section, that wasn't as clear as it could or should have been, I'll revise that now.

[Funk@lex]

I need help to extract dats.
When i try the extract dats function it opens a window so i go in my steam/steamapps/common/FTL Faster Than Light/ directory
And it is empty, the program does not see ftl.dat at all.
The game is updtaed, the mod manager is updated, i dont know what's the issue.

[krraaken]

thanks from 2019

[Gmr Leon]

Glad to help! =)

[Gmr Leon]

Hey Little Space Mouse, sorry for the delay! Have you tried opening up the sample mods that come with Slipstream? It should come with two called Beginning Scrap Advantage/Engi Scrap Advantage, which when opened (via, say, 7zip) will have a folder called mod-appendix, within which is a metadata.xml file.

You can use that as a template for your mod (which I imagine is what you're trying to do), but you can also simply create a metadata.xml file from scratch once you know the proper formatting it's looking for. Hope that helps! Sorry I didn't mention it above, but thank you for highlighting that!

I think perhaps some previous version or something I was reading at the time had me thinking it included a sample metadata file outside the sample mods, but clearly that's changed. =O

[Little Space Mouse]

No problems on the delay! And thank you, because I found the xml file right away in the sample mods!

[Little Space Mouse]

So, when trying to order and sort mod files, I can't seem to find metadata.xml to put into the folder. I have Slipstream set up, and I'm pretty sure I searched through it all.

[Vex'd]

Thanks! Yeah, after doing some testing I discovered the last version of two same-named events both work. Thanks again!

[Gmr Leon]

Heya! So, if you edited the base files instead of making appends, you should make them appends. Just safer that way. If adding new text to an old event, I'm not 100% sure, but I would think if you copy & paste the old event text into the append file, then make your changes, it should add to it without issue.

Just keep the pathing the same (i.e. same event name, same structure) to ensure it's adding smoothly. Hope that helps!

[Vex'd]

Also, if I want to add new text to an old event, how do I do that with an append?