Starbound: Ship Replacement Guide by Modding

Got a race that you like and a ship that you don’t? Yet no one on the Workshop has made a mod to give it the ship you want? Here’s how to do it yourself.

Getting Started

Tools and Organization

First, you’ll need a way to extract .paks, and to create them if you want to release the mod. While Starbound does technically come with a tool for that, a lot of people – myself among them – prefer something with a graphical interface. I use PAKit[pakit.ibraheemrodrigues.com]. Make sure to read the Guide on the site for installation and basic functionality instructions; it’s not hard, but you’ll need to point it at a few specific files.

Once that’s done, I recommend organization. Observe:

/workfolder/ is where I put extracted paks that I’m working with. /My Mods/ is where I put works-in-progress. Your own organization approach may vary, but I recommend keeping “things I’m making” separate from “things I’m extracting”.

Next, you need a race and a ship. If you’re working with a vanilla race or ship, you’ll find their content in /assets/packed.pak.

Workshop races are a trickier matter. The easiest way to find them is to middle-click on the mod in question in the workshop, to pop it out in a new window. The new window will have the URL on it:


You can see it here. Look in the pink rectangle there and you’ll see a number. Copy that entire number, that’s the Workshop ID. You can also get this number by right-clicking on the workshop page and selecting Copy Page URL, but you’ll have to paste it somewhere to just get the number.

Next, go to your Steam Library on the same drive Starbound is installed to. It should look somewhat like this:


See in the top right, above all those numbers? That is where you put the Workshop ID. Hit enter, and it will search for the mod for you. It will, usually pretty quickly, find a folder with that number as its name. Enter that folder and copy the .pak elsewhere, wherever you intend to work with it at. If you’ve gotten a ship this way that you don’t intend to use in its original mod, you can unsubscribe now; you’ll still have to be subscribed to the race you’re playing, of course.

When you have that, copy the /ships/ folders to separate locations, keeping the structure intact. That is to say, don’t take /floran/ out of /ships/, move the entire /ships/ folder. Certain ships also have additional blocks in other folders, the Soma being the main one that comes to mind. If you’re working with a ship that has those, make sure you copy those folders too (and keep the folder structure intact!), or you’ll crash. Lastly, if you’re replacing the ship of a modded race you want to play as, copy that race’s _metadata file, and set that aside for later.

Replacing a Ship

Alright. Now you have your race’s original ship and your desired ship extracted. Open those folders up and take a look.


Now, this is a lot of files! The good news for you is, this is way easier than it looks. Note first how each is named. The easiest way to do this is to copy everything except blockKey.config from the ship you want over the current ship, and rename the .structure files to match what the race currently has. In this case, I would rename all the .structure files – but not the .pngs! – to vulpesTx.structure. The .structure files you copy will point to the names of the pngs used by the new ship, without any further editing. And because the .structure files still have the original name, the race will already be pointing to those. This way, you don’t have to mess around with JSON .patches, which can sometimes be a pain.

There’s just one more thing to address, and that’s the blockKey.config. Now, the easiest way to do this is simply to copy that from the new ship as-is and leave it alone. This, however, would leave you with the new ship’s SAIL, locker, etc – which is a problem if it’s a ship for a race you don’t have installed. For example, maybe you want that nice black-and-white Soma but you don’t use the Ningen. That’d crash because the furniture doesn’t exist, so, let’s open that up before copying it over. Open the race’s original blockKey.config too.


I’m using Sublime, but Notepad works just fine too. You’ll see that this ship points at Apex resources. Check the race you want to use to see how their objects are named, and – if you want to use the race’s original objects – correct the ship’s blockKey.config to match for those specific parts before you copy it over.

Creating the Mod

This part’s easy. Usually.

Go to your /mods/ folder, and create a new folder. This one can be named anything; that’s your new mod. Next, put the /ships/ folder you’ve been editing in there. If you’re working with a ship like the Soma that also has an /objects/ folder, also put that in the main mod folder, on the same level as /ships/.

Now, this is where _metadata comes back. Open the race’s _metadata in Notepad, it’s just a plain .txt. It should look something like this:

{
  "version" : "Alpha 1.2",
  "author" : "Khioni",
  "tags" : "Species",
  "description" : "FF12/Tactics (Ivalician) Moogles in Starbound.",
  "name" : "projectmooglebound",
  "friendlyName" : "The Moogles of Ivalice"
}

As you can see, there’s both a “name” and a “friendlyName”. The “name” is the one you need here, as that’s the internal name used for an “includes” section, used to make sure it loads after the race in question so it overrides the original ship.

{
  "author" : "Syovere",
  "description" : "This is a sample metadata for a mod to replace the Moogle's human ship with something else.",
  "friendlyName" : "I Want A Soma, Kupo!.",
  "includes" : ["projectmooglebound"],
  "name" : "kuposoma",
}

Your folder structure should, when you’re done, look like:

/Your Mod/ships/moogle/
/Your Mod/objects/ (if needed)
/Your Mod/_metadata – make sure you haven’t left a .txt extension on it.

With that, you should be on your way.


Thanks to Syovere for his great guide, all credit to his effort. you can also read the original guide from Steam Community. enjoy the game.

Related Posts:

Post Author: Robins Chew

Leave a Reply

Your email address will not be published. Required fields are marked *