From Starbounder - Starbound Wiki
Jump to: navigation, search

Quick Navigation

Modding Icon.png
Modding Icon.png

Portal - Basics - JSON - Lua - Assets - Guides

Many aspects of Starbound are available for modifying or expanding, from items and monsters, to villagers, towns, and even whole planets.

Installing Mods

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 need to place the files in Starbound's mod directory Starbound\mods\. If purchased from Steam, the main Starbound folder is usually Steam\steamapps\common\Starbound. 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 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 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 resources 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.

Text Editing and suggested text editors

Simple answer: Just about anything except Windows Notepad.

Long answer: see this list of suggested text editors and a few tips for using them with JSON and Lua.

Graphics Editing and suggested image editors

You can see this list of suggested image editors and this Starbound art styling guide.

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

More information

The official modding forums

The official discord server has a #modding channel

The IRC channel ##starbound-modding in Freenode. 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.