242 ratings
Basics to Modding Starbound[Outdated]
By Xanthur and 1 collaborators
Starbound by nature was designed to be a safe haven for modders and casual players alike. Read this useful guide to set yourself in the right direction to make simple file edits. Be warned though, these methods will allow you to cheat.
Outdated guide
Hey guys,

Unfortantely this guide is outdated and will remain oudated. Between school and work I don't have much free time to devote to this guide.

If anyone would like to become a contributor let me know.
Introduction - What we know

Welcome to Stage 1 of the Starbound beta: Current Build: Frustrated Koala.

The nature of a beta test is to try your hardest to break the game, and while having a character dedicated to being legit, sometimes you want to explore the game. As we've been warned, game-saves and character files may be deleted upon new version releases. I condone anyone who uses these methods to quickly put themselves to speed and not ruin the game experience for anyone else.


Right now, the game is pretty much client-sided. This means when you join a server, the server is not making sure the packets(information) you send it are legit(match up to what the server should receive). This means you can freely edit your game to do whatever it wants, except anything do to with generation.
You can make dirt blocks count at gold bars, or change your pick to have a radius of 20 instead of 3.

Keep in mind if you're running a server, there is absolutely no server protection. Many people will use applications such as Cheat Engine to manipulate packets and alter the game in whatever way they want. I highly suggest selectively inviting people to your server and keep it password protected.

What you need

Before we begin editing files, you're going to need a file editor. Notepad on windows is extremely limited and does little to format. I suggest downloading a lightweight-code-enhanced editor such as:
  • Notepad++ (What I use)
  • Textplus
  • Sublime Text (My favorite, but it does cost money)
  • TextMate (Also great)
I'm sure Linux users will find Vim works perfectly.
File Hierarchy
Let's take a look at how Starbound organizes its files. Fortunately for us, it is neat and extremely organized. Everything we could ever need is located in the assets folder.

If you have an idea of what you're doing, check out the player and universe folders and see if you can parse anything!

Before you start fooling around with anything, please be sure to make a folder somewhere to create backups of every file you alter. If whatever you change messes up your game you'll easily be able to fix things by changing the original files back where they belong.
If you forget to backup, you can always go into steam, right click your game, press properties and then Local Files, finally click "Verify integrity of game cache". This will point out any changed files and replace them with their correct version.

After you have a folder setup, think logically of what you want to achieve:
"The picks are way too slow for my liking, I don't want to cheat but I do want to save some extra time."

Based on your logical thinking, you should be able to logically locate the files you would like to edit.
From the assests folder, Items stand out because the Pick is an item!
Again, logically, Tools is the only thing that stands out.

You can find anything you need by looking around, so do take the time to peak around and see what you can find!

If you've never done this sort of thing before, you might be confused poking around saying "Wait but I can't open these files!" This is exactly why I advised you to download a good lightweight editor.
Most of these files are still plain text, while others do have some sort of "encryption".
Here's a list of weird extensions you will encounter:

  • .animation
  • .frames
  • .augment
  • .spacebiome .surfacebiome(ect)
  • .consumable
  • .miningtool
  • And many many more

If you installed Notepad++, it adds a very nice shortcut when you right click a file named "Open with Notepad++". With any other program you can do the standard File->Open.

Going off the example from before, let's open up a pick- copperpickaxe.miningtool

Let's look at the file

As complext as it looks, it's very simple. The developers have done a pretty good job making everything readable. There are a couple of guidelines you must always remember though:

  • Commas after every argument, with the exception of the last.
    If you look at the file, the end of an argument comes a comma. This symbolizes that a new argument is coming, and the previous has finished.
  • Names and filepaths are always surrounded by quotes.
    Number values don't need a quote.
  • Files have many attributes, you can add attributes to files and even take some away.
    This is how many edits will be made.

Back to the example:
Pickaxes do damage to tiles, increase the damage, you decrease the time it takes to break those tiles.
"tileDamage" : 0.9,
Make that value a little higher,
"tileDamage" : 1.5,
Save the file, load up the game, and get to work.
Different attributes on different items
Do you hate having to hunt for coal? I know I sure do, want to just explore the vast universe without having to worry about constantly looking for coal to refuel? Why don't we use something more common- dirt maybe, but dirt isn't fuel, or is it?

Let's find coal ore to figure out how fuel works. Using our logical thinking again, you might find yourself in /assets/items/materials, however ores are found in /assets/items/generic/crafting instead.
Lets look at it.
"itemName" : "coalore",
"rarity" : "Common",
"inventoryIcon" : "coalore.png",
"description" : "It's coal. A decent source of fuel.",
"shortdescription" : "Coal Ore",
"fuelAmount" : 2

Oh, look! "fuelAmount" sounds pretty relevant. That must be how coal gives fuel to our ship. We could make this number higher, or we could have much more fun with the game files.
Let's find dirt in /materials and look at it.

"itemName" : "dirtmaterial",
"rarity" : "Common",
"inventoryIcon" : "dirt.png",
"dropCollision" : [-2.5, -2.0, 2.5, 2.0],
"description" : "Dirty looking dirt.",
"shortdescription" : "Dirt Block",
"glitchdescription" : "Statement. Dirt. Clarification. Just dirt.",
"florandescription" : "Filthy dirt!",
"category" : "Material",
"materialId" : 8

It looks like there's no "fuelAmount" attribute on this item, why don't we add it under "materialId"?

"materialId" : 8,
"fuelAmount" : 200

Again, don't forget the comma! Let's make it 200 just for the point of proof and take a trip to our ship..


Creating your own recipes
Now I for one hate ending up dashing over planets scouring for surface chests in hopes of getting a vanity item I don't already have, it's simply not fun for me and detracts from the game! Hell, I even hate not having simple movement techs available to me like Energy Dash or Pulse Jump! Well, there's not much need for that now!

Now before we get into this, these changes will only affect newly created characters depending on where you place the blueprint. I'll explain more as I go through!

For this example, I'll be using the Human Mech tech as an example, and we'll be crafting it for one torch.

Our config of choice will be player.config located in the root assets folder, \Steam\steamapps\common\Starbound\assets. We'll also be using the recipes subfolder, and for the sake of testing and simplicity, we're going to use the "starter" then the "plain" subfolders so our new character is created knowing how to make the items.

So first thing is first, we need to find the name of the item we're going to be adding. We're going to navigate to \Steam\steamapps\common\Starbound\assets\tech\mech\humanmech\ and open the humanmech.techitem file in notepad++. This is only to double check the item name so we don't end up crafting "Generic Item", the placeholder for missing items but also to minimise crashes.

Now that we have the name, "humanMechTech", we're going to open our player.config and navigate to the blueprints section. It's visible from the top, but the line reference we'll be using is 27. Start a new line after copperarmorhead and then type "{ "item" : "humanMechTech" },", remembering to match the layout with the surrounding items.

That was easy! Now we need to add it as a recipe, in the E:\Steam\steamapps\common\Starbound\assets\recipes\starter\plain folder. I like to use campfire.recipe as my template, since it already has "{ "item" : "torch", "count" : 1 }" as an input. We can go ahead and delete line 3, as we don't want refined wood in our recipe. Now, doubleclick "campfire" on line 7 and change this text to humanMechTech. We can ignore the groups for now as this is the basics of adding a recipe.

Now, using either Ctrl+Alt+S or simply clicking "File > Save As", however you prefer to do it, save it as "humanMechTech.recipe", but before clicking "Save", we need to make sure it saves as a .recipe and not a .txt. Where it says "Save as type: Normal text file (*.txt)", we can click the dropdown and change that to "All types (*.*)" then hit save!

Now when you launch the game, create a new character, grab your torches and craft the tech! Use it, then go to your tech station and become the mech you were always meant to be!
So far you've been taught basic file editing skills. With these skills you can start exploring new possibilites. But what happens when you want to start sharing your work? To begin with, adding mods and removing them isn't very efficiant.
Starbound offers a great way for us to override the original assets so we can freely mod files without having to mess with the originals.

To start, go to your Starbound directory. Create a new folder, you can name it whatever you want, but the obvious name should be /Mods.

In this folder you can place other peoples modifications, as well as your own.

Start out by making a new folder inside of /Mods named /CopperPickaxe.

As the name suggests we're going to override the CopperPickaxe, these names are just for orginizational purposes.
Inside /CopperPickaxe we want to mirror where the Copper Pickaxe is located from the assests folder:
So we create a few more folders until we get something looking like this
Find the copperpickaxe.miningtool in the original assets folder, and copy it into the tools folder of your new modding directory.

Make the edits you wish and navigate back to the Starbound directory.
Open up the folder for your operating system, I'm using windows so thats win32.
Open up bootstrap.configPut a comma after "../assets" and link to your new modification "../Mods/Copperpickaxe".

Save the file, run your game, and boom, you've just made edits without touching the main assets.

DO NOT forget to watch your formatting.
Here's a list of useful links for your to explore!

Official modding forums:
People are doing a wonderful job submitting content already, check it out!


Expect this guide to be updated with new information as new discroveries come up, and as people add onto what was written here. I'm open to anyone who has suggestions and anyone who wants to contribute.
This guide will be an ongoing work-in-progress to aid everyone.
< >
KittyBiscuits Dec 13, 2015 @ 4:34pm 
Hi I wanted to thank you so very much for making this easy to read tutorial! I have never tried modding before but I wanted to badly to add some pretty new decorative and functional furniture to the game and today I learned how to unpack the files and have been looking at stuff a little confused but with your help I think I'm gonna make some progress! Thank you!!!
Plague Mouse Jul 15, 2014 @ 7:20am 
How do I find my player.config file?
secretspy410 Feb 18, 2014 @ 1:51pm 
and you switch mods on and off from the store page
secretspy410 Feb 18, 2014 @ 1:49pm 
to bad steam doesn't offer a modding servace so you push a button it will activate the mod then you press it again to de activte it
Domo Feb 17, 2014 @ 2:46pm 
Guys chill, You need an assest unpacker. Assets have been put in a compressed file in a patch so don't worry. Just download one, run it, then you shouldbe good to go! Hope this helped

Flying Horse Cat of Doom Feb 16, 2014 @ 8:21am 
assets only has my minecraft weapon mod.WHAT DO I DO :(
Seanerzat Feb 14, 2014 @ 1:34pm 
Help! When I look inside the asset folders, there isn't actually any files on the inside (other than user/songs, that has all the songs). Starbound is running 100% fine on my Mac but I really want to mod. D:
Aaron ਨੈ ਸਸਦਠਐ Jan 30, 2014 @ 8:40pm 
I think you mean EditPlus, not TextPlus
Lerrete Jan 28, 2014 @ 9:00pm 
Sorry If i seem a bit uninformed, but im a little confused in terms of creating mods using a Mac computer, ive been very interested in modding and seeing if i could create my own, however this guide has little specifications and guides for mac... any alternatives?
Xanthur  [author] Jan 26, 2014 @ 4:51pm 
As of now this guide is completely outdated and useless. It'll be updated shortly however :-)