FTL Modding Tutorial: Creating a Playable Ship

Hi, all! FTL is an awesome game, isn't it? So many different ships to play with, so many different weapons to try out, so many encounters.

But if you play it a lot, you may find yourself wanting to go beyond those limits. Wanting to make up your own ships, weapons, events. Fortunately, FTL is a very moddable game, thanks to some great tools the modding community have written.

I'm here to teach you how to create a ship for yourself. There's a handy utility called FTLEdit written by Darkfrost, and we're going to use that to do some of the work for us, but we'll still have to do quite a bit ourselves. (There's another editor too, called FTL Ship Creator and written by tazardar, but I haven't tried that one.)

If you instead want to create enemy ships, to attack the player rather than for the player to use, then a lot of this guide will still apply, but bits of it won't. You'll have to explore a bit more.

Ready to create a new playable ship? Then let's get started.

Step 1: Install FTLEdit, GMM and a Mod

There are a couple of required steps before you actually start modding. There are certain conditions under which all FTL mods must be distributed, that basically mean using Grognak's Mod Manager (GMM) is a must. You're going to need to have GMM working if you ever want to distribute your mod, and it does some useful things to the data files too; not to mention it lets you try out every other mod in the FTL mods forum. So you'll need to install it. A couple of tips:

When you've got them installed, check it's working. Run GMM, click "Beginning Scrap Advantage", click Patch. When GMM finishes, launch FTL (you may have to do it directly rather than letting GMM launch it for you), and start a new game: if you see a blue option saying "(Mod) Strip a near-by asteroid for scrap", the mod is installed!

Since you'll be creating a .ftl mod, and .ftl files are renamed .zip files, you'll also need a zip program installed. I recommend 7Zip, but WinZip will do fine as well.

Step 2: Design

Okay. With those preliminaries out of the way, time to move on to actual mod design!

The first step is: Figure out what you want your ship to do! Plan the image you're going to use for the ship, what weapons and crew and drones you want the ship to have, any augments, what systems you want to start off levelled-up or have absent entirely.

Step 3: Draw the Graphics

Obviously you'll need to draw the ship. Where "draw" may mean draw in a graphics program, or it may mean extract them from some other source. For my Starcraft mod, this meant loading the Starcraft editor, zooming in on one ship, taking a screenshot and then tidying it up in GIMP.

It's worth knowing what you're aiming for. If you look at the images for the built-in ships, they're all between 400x400 and about 700x400 pixels. (If you don't know where to find those images, they're in your FTL install directory, under resources/resources.dat-unpacked/img/ship . Take a look at all the images in this directory – it's pretty helpful and interesting.)

You'll also want at this point to give a little consideration to mount points: where do you want the weapons to appear on the outside of your ship?

Step 4: Floor Plan in FTLEdit

Now it's time to fire up FTLEdit. If you haven't launched it before, then once it loads you'll need to click Options and specify the path to where your FTL install is. If you've run GMM as I told you to, the resources directory ought to contain unpacked versions of data.dat and resources.dat. This is what you need to point FTLEdit at. There's no OK button in this dialog - just close it once you've filled in the directories. You'll know it's right if you can edit an existing ship successfully.

Now, edit one of the existing ships. You should choose the ship which you want to replace in the hangar with your new ship. (In order for your ship to be playable by the player, it has to replace one of the 18 ships that goes in the hangar.)

FTLEdit will open with the floor layout of that ship. Now do the following:

Step 5: Options in FTLEdit

Click FTLEdit's Options button. Drag the dialog to somewhere that isn't overlapping the main FTLEdit window. Now go through the options for crew, weapons, drones etc, adjusting them as you like. A few notes:

When you're done, click "Export Ship" and "Export the .ftl package". This will produce a first draft of the .ftl file that will form your mod. It's nowhere near finished, but it's a good first step. Copy the .ftl file over to your FTL install's mods/ directory. Make a backup copy of it somewhere else as well if you like.

Step 6: Unzip the .ftl file and Add Images

Right, it's time to fill in the gaps in what FTLEdit produced. Rename your .ftl file to instead end .zip, and unzip it to a directory somewhere. Go into that directory. This I'll call your mod root directory. It should contain two subdirectories, data/ and img/. The img/ directory needs to contain a subdirectory called ship/ with all your ship images in, but FTLEdit doesn't put them in there. So that's your first task: copy your ship image into your mod's img/ship directory. Give it the name [myship]_base.png , where [myship] is what you specified as the "Img" setting in FTLEdit's options.

You also need to add an image called [myship]_floor.png . For most mods this is just an empty transparent .png file, but if you feel like it you can draw a floor layout. If you don't have an easy way to create a transparent png, download this one and save it as myship_floor.png in the same directory, img/ship inside your mod directory.

Once you've done this, you ought to be able to zip up your mod into a .ftl file and try it out. It'll have a bunch of glitches that we'll fix in later stages, but it ought to be broadly playable. To turn your mod directory into a mod and install it, these are the steps:

It's best to do this regularly. For example, after each of the remaining steps, you could do this process to test out your work.

Incidentally, if you happen to have cygwin installed, you can do all the above with this one line:

pushd mods/myship ; zip -qr myship myship ; mv myship.zip ../myship.ftl ; popd ; ./modman.exe ; ./ftlgame.exe

Step 7: Edit the Blueprint and Add Weapon Mounts

Now, inside your mod's data/ directory is a key file called blueprints.xml.append. Open this file in a text editor (Notepad would do if you don't have anything else).

You ought to be able to see how the XML in this file matches up to what you defined in FTLEdit's options screen. The power levels, weapons and so on should all match what you set. If you want to change them, you can do that here.

In particular, if you want your ship to have fewer augments, weapons or drones than the one you were editing had, then you'll need to remove some lines here, because FTLEdit unfortunately leaves them in.

FTLEdit does now produce a layout xml file, including the offset, which is great as you don't have to do that yourself any more. (Make sure you have the latest version of FTLEdit, version 0.91 as of 31st December 2012, as that step is a real pain to do manually.) But you do still need to define weapon mount points: that is, the places where weapon images poke out from behind the ship.

This is pretty easy. Open the ship image in any image editor. Position your mouse cursor over the point where you want the rear corner of the first weapon to be. Now look at the editor's status bar for two numbers: these are the x and y coordinates of this mount point. Note down these numbers. Repeat for each mount point (you usually want 4). If your ship has the Artillery Beam as on the Federation Cruiser, do the same to get an extra pair of mount point coordinates for where the beam should fire from.

Edit the file called [myship].xml that's in the data/ directory of your mod root. For each mount point, add a line looking like this:

<mount x="361" y="59" rotate="true" mirror="false" gib="1" slide="right"/>

The x and y numbers are the coordinates you noted earlier. "rotate" should usually be true: true means point to the right, false means point upwards. "mirror" should be true for weapons that poke up-and-right (usually on top of your ship) and false for weapons that poke down-and-right (on the bottom). "slide" indicates which direction the weapon slides out when you activate it.


If you have problems with your mod not working, the most common cause is some XML that's slightly wrong or not as FTL expects it. You need to very carefully check your XML in blueprints.xml.append and myship.xml, to make sure that every <tag> either ends with />, or is matched by a closing </tag>.

Step 8: Choose a Shield Image

You need to choose a shield image that's about the right size for your ship. Look at the existing shield images in your FTL install's img/ship/ subdirectory – everything ending in _shields1.png. They're all different sizes, and you want one that's big enough to enclose your whole ship. You don't have to use the same image that the base-game ships use, but you do need to use something that's an ellipse.

If you conclude that, say, the Zoltan Cruiser's 640x400 shield will do – the image energy_cruiser_shields1.png – then edit the blueprint to add


(Note that you leave off "_shields1", because FTL adds that at the end.) If you're creating your own shield image file called myship_shields1.png , you don't need to add to the blueprint; just put the shield image in your mod's img/ship directory.

The second half of this task is to edit the ELLIPSE dimensions in the myship.txt file. This is important because if you don't change it, then no matter what the image looks like, the shield will only protect rooms within a 400x400px circle: outlying rooms can be hit even if your shields are up! You need to set the numbers after ELLIPSE to half the width and half the height of the shield image.

This would be a good time to rezip your mod and check it out again, following the same instructions as in step 6.

Step 9: Choose Room Images

You should choose or create images for the individual rooms in your ship. Go and look in resource.dat-unpacked/img/ship/interior . All those images are possibilities to appear in the rooms of your ship. This isn't just graphical polish, because you need to select which space of the crewable rooms is the one where the operator needs to go. By default, FTLEdit doesn't give sensible settings here. Room images come out very distorted, and some rooms can end up not crewable at all, which imposes a major gameplay penalty.

So what you need to do is bring up your ship, either in FTL with the mod installed, or in FTLEdit; simultaneously open the blueprint in a text editor; and also have a thumbnails view of img/ship/interior to hand. For each of the systems and subsystems on your ship - probably all eleven, unless you've deliberately omitted some - you need to do the following steps.

Step 10: Make a Cloak Image

This technically isn't required, but if you don't do this, whenever anyone in your ship cloaks they'll see a sudden black box appear behind the ship.

The image you create should be a version of the ship image, but with the edges highlighted in grey/white. Importantly, you also need to expand it away from the border by 10px in each direction: so the cloak image should be 20px larger than the ship image in both x and y. I found the following sequence of GIMP commands produced a reasonable cloak image, but you can produce one however you like.

Step 11: Make Miniship Images

We're nearly done. There's still one step you should do before releasing your mod, which is to create a thumbnail view of your ship for the Select Your Ship screen and the Highscores screen.

It's mainly a case of shrinking the ship image to 191 x 121 px and saving it in your mod's img/customizeUI directory. To fit the look of the base-game ships, you should probably add a small glow behind the thumbnail. You can do this in GIMP using feathered selection similar to how I described for creating a cloak image.

Note that in the hangar's Select Your Ship screen, only the primary versions (Type A) of each ship are shown. However, you should create thumbnails for any secondary versions (Type B) you overwrite too, so that they show up correctly in the highscores list.

Step 12: Gibs

This isn't necessary, and a lot of modders skip this step entirely. But if you want to make your ship looks nice when it explodes, then take a look at the existing ships' _gib1.png through to _gib6.png, and at the section of an existing ship's .xml file such as circle_cruiser.xml (in data.dat-unpacked), and make yourself some images for the different parts of the ship, and define the <explosion> to say which direction each of the gibs should fly off in. Note that gib1 will be on top of the rest, then gib2, and so on, down to your last gib (often gib6) which will be underneath all the others.

And Finally: Playtest!

Now you've got all the skills you need to make a ship every bit as good as the ships in the base game. But odds are, your first design will be missing the mark somewhere. It might be too strong, too weak, unbalanced in one way or another. The only way to find out is to playtest it, and then playtest it some more! Keep on trying changes until you're happy with the quality level, and then upload the .ftl file somewhere publicly accessible and go and post about it on the FTL Working Mods Forum!

This tutorial was written by alextfish, creator of the Starcraft mod. SDG.