From Starbounder - Starbound Wiki
Jump to: navigation, search

Quick Navigation

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 /assets/scripts/API 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?!

We are still in the early stages of learning about modding. Much of what we know is incomplete and may change during the course of beta. 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.

  • For help getting started check out this step by step guide, Modding Basics.
  • You should read through a good sampling of the existing JSON and Lua code before changing any files, or creating any new files.
  • Download some sample mods (make sure they are at least from Angry Koala version or later and include a .modinfo file) to learn from.
  • Information on the Lua API, limited as it currently is, is documented in some Lua files in the /assets/scripts/API folder (they are meant to be read, not executed), and more is in this thread and although it may sometimes be a little outdated, should help.
  • Create a .modinfo file for your mod. There is some information in this forum post.
  • For adding to or overriding existing functionality, you will likely need to use the __merge functionality to add a new recipe or starting item to the player.config file.

Older, Outdated Info

  • There is also an outdated tutorial on Steam about basic modding, but which doesn't account for __merge functionality or .modinfo files.
  • 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.

Where is feature X?

Remember, the game is still in beta, so whole parts of it are still missing!

Here's a very incomplete list of planned features that will assist modders:

  • .pak file support with included compressor/decompressor for simpler distribution of mods
  • A less restrictive, more powerful Lua API

Text Editing

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.

Graphics Editing

What image editor should I use?

Please see this list of suggested image editors.


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.

Mac specific problem with .DS_Store files

Currently (beta v. Offended Koala) the Mac version will crash if the data directory ( ~/Library/Application\ Support/Steam/SteamApps/common/Starbound for Steam users) is opened with the Finder, because doing so creates invisible .DS_Store files, and these cause the Starbound client to crash on launch.

Until the bug is fixed, Mac-based modders can remove the files from their Starbound directory using the terminal (the following command removes them from all Steam apps - this should be non-problematic, but if so append the Starbound directory name to the path):

find ~/Library/Application\ Support/Steam/SteamApps/common -name .DS_Store -exec rm {} \;

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 modding forums

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 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.