Many aspects of Starbound are available for modifying or expanding, from items and monsters, to villagers, towns, and even whole planets.
Chucklefish Games provides two official sources for mods, the Starbound Mod Repository and the Starbound Modding Forum. Steam users can also browse the Steam Workshop. Once downloaded, you will want to place the files within Starbound's mod directory:
If purchased from Steam, the location of the main Starbound directory folder typically looks like this:
Workshop mods are automatically downloaded in Steam\steamapps\workshop\content\211820.
They do not need to be moved to the Starbound\mods\ folder, the game will load them automatically.
Mods can be found in three forms:
- compressed (.zip, .7zip, .rar, ...): those are generally unpacked compressed mods. Starbound cannot handle them, and you'll have to unzip them first.
- unpacked: those are the raw files, directories, etc.
- packed (.pak): those are "packed" in a format that Starbound can read, and is generally prefered for faster loading.
A more in-depth installation guide is available on the official forum.
How do I mod Starbound?
The moddable assets are located in the Asset Tree, which is located in your Starbound directory under /Starbound/assets. There are several types of assets. Editing an existing asset will change the base behavior of the game. You can add new assets, although getting those assets into the game may be tricky depending on what you're trying to add. The official modding forums are the best source of up-to-date information on specifics.
- JSON Objects: There are hundreds of JSON configuration files in various directories inside /assets/, with dozens of different extensions, like .config, .frames, .animation, .gun, etc. Any files with extensions that do not match the ones listed below are probably JSON config files.
- Lua Scripting: Monsters, NPCs, and certain objects use Lua scripts to control their behavior. Lua scripting has a lot of potential, but currently suffers from severe scoping limitations. Lua files always end with the extension ".lua." The Lua API is documented in some Lua files in the 'Starbound/doc/lua' game's folder, and is also explained here and although it may sometimes be a little outdated, should help.
- Sound files: File extensions are either ".wav" or ".ogg"
- Graphics: File extension is ".png" for graphics.
Yeah man, but how do I mod Starbound?!
The developers are very responsive to requests from the community and have already implemented some things by request since the beginning of beta. The best way for you to learn how to mod is go to the official forums, do a bunch of reading, look at some existing mods, and of course do extensive browsing of the asset files until you form some understanding of them.
- Multiple ressources are available to get you started, pick your media of preference:
- The Modding Basics is a step-by-step guide on this very wiki
- An unofficial Ebook was created especially for those completely new to the modding scene.
- This video covers everything from how to unpack your Starbound assets to making a basic decorative custom object, how to make a recipe for that object, how to learn that recipe and finally how to pack and distribute it when you are done
- For more specific needs, the official forums have a "tutorial" tag that you can browse.
- Information on the Lua API is documented in .md files in the Starbound/doc/lua folder.
- If you have any problems, comb through the included assets. They are a rich source of examples you can follow. Before you try to make anything complex, you should start with copying something simple.
- You can also download some sample mods (make sure they are up to date, as the mod specifications changed a few times in the beta) to learn from.
Where is feature X?
Now that the game is officially released, if there is a feature that is in your opinion missing from the game, you are free to submit mod requests at Offical Starbound Mod Forums. Another area that allows modding requests is the subreddit /r/starboundmods.
What text editor should I use?
This is a complex question, but the simple answer is, "Just about anything except Windows Notepad."
We have a list of suggested text editors and a few tips for using them with JSON and Lua.
What image editor should I use?
My game keeps crashing!
You can start by checking the log file. You can find errors in there telling you which line in your code caused the crash. Loading the multiplayer server will give you a console, but restarting it frequently is tedious.
An online JSON parser will help catch some common mistakes, such as missing commas and unmatched braces in your modified files. For more information about JSON, see the JSON page, or see the index of JSON configuration file types here.
How can I help the modding community?
Check out Modding:Modding/DocumentationTODO to see a list of things that need to be done for modding documentation on this wiki.
Where can I get more information?
The official discord server has a #modding channel
There is also the IRC channel ##starbound-modding on the Freenode network, which can be accessed here. Please note that this channel is dedicated to the ins and outs of modding, and is not the place to ask about a mod you downloaded! We don't kick or ban for minor netiquette breaches, but if the room is busy, be courteous and obey the rules or you may have a problem.
If you use the IRC channel, follow these simple rules:
- Use a pastebin like pastebin.com for anything over 2-3 lines.
- Check the log files first. If there's an error you don't understand and want us to look at, post it on a pastebin for us to look at, along with any relevant code.
- Do not spam the chat with excessive emotes or offtopic chat. Some offtopic is fine, but if people are talking about modding, try not to spam up the chat with fluff. You can go to #starbound or #starbound-overflow for that.
- Constructive criticism is welcome, but be thoughtful and respectful of others.
- Don't walk into chat and ask "hay guise how do i mod lol." We're all bootstrapping our own modding efforts by doing a lot of reading through the example code, reading others' mods, and experimentation.
Also remember to check out this mods to give you a little inspiration:
- Frackin Universe
- Shellguard Expansion
- Extended Story Mod