FTL Modding Tutorial by alextfish (2024)

Hi, all! FTL is an awesome game, isn't it? So many different ships toplay 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 beyondthose limits. Wanting to make up your own ships, weapons, events.Fortunately, FTL is a very moddable game, thanks to some great toolsthe modding community have written.

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

If you instead want to create enemy ships, to attack the playerrather than for the player to use, then a lot of this guide will stillapply, 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 startmodding. There are certain conditions under which all FTL mods must bedistributed, that basically mean using Grognak's Mod Manager(GMM) is a must. You're going to need to have GMM working ifyou ever want to distribute your mod, and it does some useful thingsto the data files too; not to mention it lets you try out every othermod in the FTL mods forum. So you'll need to install it. A couple of tips:

Download FTLEdit from here and GMM from here.
When you've unzipped GMM, put it in the same directory thatftlgame.exe is in. (You can find this by right-clicking the FTL shortcut to start the game,clicking Properties, and clicking Find Target or Open File Location. ForSteam installs, look in C:\Program Files (x86)\Steam\steamapps\common\FTL Faster Than Light, or perhaps without the (x86).) When you find ftlgame.exe, I'll call that directory your FTL installdirectory. After you put the contents of the GMM zip there, this directory shouldcontain modman.exe, ftlgame.exe, and a number of subdirectoriesincluding resources/ and mods/ .
I can't provide tech support for these utilities. For problems withGMM ask in the GMM thread.

When you've got them installed, check it's working. Run GMM, click"Beginning Scrap Advantage", click Patch. When GMM finishes, launchFTL (you may have to do it directly rather than letting GMM launch itfor 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 .zipfiles, you'll also need a zip program installed. I recommend7Zip, but WinZip will do fine as well.

Step 2: Design

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

The first step is: Figure out what you want your ship to do! Plan theimage you're going to use for the ship, what weapons and crew anddrones you want the ship to have, any augments, what systems you wantto 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 meanextract them from some other source. For my Starcraft mod, this meantloading the Starcraft editor, zooming in on one ship, taking ascreenshot and then tidying it up in GIMP.

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

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

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 pathto where your FTL install is. If you've run GMM as I told you to, theresources directory ought to contain unpacked versions of data.dat andresources.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 whichyou want to replace in the hangar with your new ship. (In order foryour ship to be playable by the player, it has to replace one of the18 ships that goes in the hangar.)

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

Click "Show floor" to remove the grey background to the rooms.
Click each room and door in turn and press the Delete key.
Click "Load base", and browse to the image you created earlier. Use"Move base" to position the ship image behind the grid.
Draw the rooms using "Add room". Click-and-drag to initially size aroom; right-click-and-drag to resize. I recommend you first place allthe rooms, and only then add all the doors using "Add door".
Add systems using the system icons for weapons, shields, etc. Youneed to specify which room will have a system even if you don't wantthe ship to start with that system. If you leave any systemsunplaced, the ship will be unable to ever gain that system evenif the player buys the system in a shop.

Step 5: Options in FTLEdit

Click FTLEdit's Options button. Drag the dialog to somewhere thatisn't overlapping the main FTLEdit window. Now go through the optionsfor crew, weapons, drones etc, adjusting them as you like. A fewnotes:

In the "Important ship settings" section, it's simplest if you setthe "Img" and "Layout" to the same thing. For simplicity this should be all lowercase and with no spaces (but underscores _ are fine).
Do not change the "ID" other than to one of the 18 ships in thehangar.

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 yourmod. 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 backupcopy 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. Renameyour .ftl file to instead end .zip, and unzip it to a directorysomewhere. Go into that directory. This I'll call your mod rootdirectory. It should contain two subdirectories, data/ and img/. Theimg/ directory needs to contain a subdirectory called ship/ with allyour ship images in, but FTLEdit doesn't put them in there. So that'syour first task: copy your ship image into your mod's img/shipdirectory. Give it the name [myship]_base.png , where [myship] is whatyou specified as the "Img" setting in FTLEdit's options.

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

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'llfix in later stages, but it ought to be broadly playable. To turn yourmod directory into a mod and install it, these are the steps:

Navigate to your mod's root directory in Windows Explorer. Youshould see two directories: img/ and data/ .
Select both img/ and data/ (e.g. by dragging a box around both ofthem). Right-click one of them and select "Add to zip file myship.zip"or similar.
When 7Zip finishes creating the archive, rename it to myship.ftl .
Move the .ftl file off into your FTL install's mods/ directory.
Run GMM. Select your mod and click Patch.
Launch FTL and take a look at your ship in the hangar!

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

Incidentally, if you happen to have cygwin installed, you can do allthe 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 calledblueprints.xml.append. Open this file in a text editor (Notepad woulddo if you don't have anything else).

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

Troubleshooting

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 yourship. Look at the existing shield images in your FTL install'simg/ship/ subdirectory – everything ending in _shields1.png. They'reall different sizes, and you want one that's big enough to encloseyour whole ship. You don't have to use the same image that thebase-game ships use, but you do need to use something that's anellipse.

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

<shieldImage>energy_cruiser</shieldImage>

(Note that you leave off "_shields1", because FTL adds that at the end.)If you're creating your own shield image file calledmyship_shields1.png , you don't need to add to theblueprint; 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 themyship.txt file. This is important because if you don't change it,then no matter what the image looks like, the shield will only protectrooms within a 400x400px circle: outlying rooms can be hit even ifyour shields are up! You need to set the numbers after ELLIPSE tohalf 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 yourship. Go and look in resource.dat-unpacked/img/ship/interior . Allthose images are possibilities to appear in the rooms of your ship.This isn't just graphical polish, because you need to select whichspace of the crewable rooms is the one where the operator needs to go.By default, FTLEdit doesn't give sensible settings here. Room imagescome out very distorted, and some rooms can end up not crewable atall, which imposes a major gameplay penalty.

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

Note the room's size. For example, the weapons room in your shipmight be width 2 and height 1.
Look in img/ship/interior for an image for that system of that size.Note that each square of a room is precisely 35x35 pixels: so in theexample we're looking for a weapons system image that's 70px wide by35px high. If you look in img/ship/interior you'll see that room_weapons_8.png is the only one of that size.
Edit the ship blueprint's line for that system to specify the imagein question. E.g. you should update the <weapons> line to sayimg="room_weapons_8".
If the system is one of the four crewable systems – weapons,engines, shields or pilot – you need to look at the image you'vechosen and see where the computer terminal is. Note which square is itin, counting from top-left starting at 0, and which wall theterminal's against, i.e. which direction crew should face when they'reusing it. The square numbers start counting at 0 and go in readingorder, so the square numbers for a 3x2 room would be:
```
 0 1 2 3 4 5
```
Now you need to change the blueprint lines for those crewablesystems further. In our example, the weapons terminal is in the right-hand square ofthat 2x1 room, i.e. position 1 (because we start counting at 0), and on the topwall. Change the line which before said:
```
<weapons power="[whatever]" room="[whatever]" start="true" img="room_weapons_8" />
```
so that now it says:
```
<weapons power="[whatever]" room="[whatever]" start="true" img="room_weapons_8"> <slot> <number>1</number> <direction>up</direction> </slot></weapons>
```
Take particular note that the line used to end /> but now it ends >.
You also need to do this for the medbay. By default, one square ofthe medbay is not standable-in. The
setting for themedbay specifies which slot is blocked by the med computer. (Don't usea <direction> parameter for this one.) E.g. for a 2x2 medbay whose bottom-left square is blocked, you'd say
```
<medbay power="[whatever]" room="[whatever]" start="true" img="room_medbay_7"> <slot> <number>2</number> </slot> </medbay>
```
If you don't want any slot blocked – likely to be the case if your medbay is 2 spaces or smaller– then the magic code is to use slot minus two, i.e. <number>-2</number> .
What if none of the existing room images fit your room? Then you'llhave to either redesign the room layout in FTLEdit to fit theavailable room images, or create a room image for your desired size.It's easy enough: just choose an image similar to the one you need,open it, expand the border to the size you want, and move bits of roomimage around until they're on the appropriate edges. Save it into yourmod's img/ship/interior directory with a new name, likeroom_weapons_51.png. Then do the same with the three coloured glowimages for the computer screen, with names room_weapons_51_glow1.png. (These should just need positioning correctly in the new border.)Then specify that new name in the blueprint: img="room_weapons_51"
If you're a stickler for making sure that none of the bits ofcloaking system or shield system go in front of doors, you may need toedit images to move bits around for several other room images.
Any images you specify that aren't the right size will bestretched or shrunk to fit. This looks awful for rooms with computerterminals, but can be okay with some others, especially the sensorsroom.
For 1x1 system rooms, you may want to just use img="computer", afree-standing terminal without any accoutrements around it.

Step 10: Make a Cloak Image

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

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

Open the ship image
Layer -> Layer Size -> increase numbers by 20
Image -> Fit Canvas to Layers
Filter -> Edge Detect -> Laplace
Press Shift-O for the Select by Colour tool
Click a transparent bit of image
Selection -> Invert
Fill tool, set tool options to fill whole selection, fill selectionwith colour #f3f3f3
Layer -> Duplicate Layer
Page Down to select the lower layer
Selection -> Grow -> 1 pixel
Selection -> Feather -> 5 pixels
Fill whole selection with colour #57c8fd
Set lower layer opacity to 50%
Export image as myship_cloak.png into your mod's img/ship directory

Step 11: Make Miniship Images

We're nearly done. There's still one step you should do beforereleasing your mod, which is to create a thumbnail view of your shipfor 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 savingit in your mod's img/customizeUI directory. To fit the look of thebase-game ships, you should probably add a small glow behind thethumbnail. You can do this in GIMP using feathered selection similarto how I described for creating a cloak image.

Note that in the hangar's Select Your Ship screen, only the primaryversions (Type A) of each ship are shown. However, you should create thumbnailsfor any secondary versions (Type B) you overwrite too, so that they show upcorrectly 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 asgood as the ships in the base game. But odds are, your first designwill 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 toplaytest it, and then playtest it some more! Keep on trying changesuntil you're happy with the quality level, and then upload the .ftlfile somewhere publicly accessible and go and post about it on theFTL Working Mods Forum!

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