From Starbounder - Starbound Wiki
Jump to: navigation, search
Mining Hazard Sign.png
Work In Progress!
Mining Hazard Sign.png

This article or section is currently in the process of an expansion or major restructuring.
You are welcome to assist in its construction by editing it as well.

Last edited by Zoniventris on 2020-06-16 20:52:03.

This article will show you the steps you need to take before you can start actually modding, and also the steps you can take after you are done modding, to pack and publish your mod.

You will need a text editor that is not the Windows included notepad.exe, as it does not support UNIX line endings. Do not use a word processor such as MS Word instead of a text editor. Only UTF-8 is supported, other encodings are likely to cause crashes.

Alternative sources for getting started in modding include the Official Chucklefish Forums, the Unofficial Modding Ebook, the third-party program ModPakHelper that can be used for both unpacking and packing assets, a video, and some more. See external links below.

Step 1 - Unpacking Assets

Furious Koala introduced a .pak format which improves loading times and eases mod distribution. This means we need to unpack the assets before we can start modding.

Note - This step will not remove or change your packed.pak file, but simply extract its content for use as reference material. Changes you make to the unpacked assets will have no effect on your game.


Current as of Version 1.3.1, June 27th, 2017

  1. Open up the main directory folder for Starbound.
  2. Shift + right-click within the folder and select Open Command Prompt/Powershell or equivalent (depends on Windows version).
  3. Type the following into Command Prompt/Windows Powershell: .\win32\asset_unpacker.exe .\assets\packed.pak .\_UnpackedAssets
  4. Command Prompt/Windows Powershell will do nothing until asset_unpacker.exe has finished. There are no progress updates.
  5. Once Command Prompt/Windows Powershell displays a message equivalent to this, "Unpacked assets to _UnpackedAssets in [time it took]s," you can close the program and move on to creating mods.


  • If purchased from Steam, the location of the main Starbound directory folder typically looks like this: Steam\steamapps\common\Starbound
  • The text typed into Command Prompt/Windows Powershell are three directory locations:
    1. The location of asset_unpacker.exe, which is the program that does all of the unpacking.
    2. The location of Starbound assets, or Mod assets, to be unpacked.
    3. Where you want the unpacked assets to be dumped. This third string can be changed to whichever location or name you prefer.


(The following assumes Starbound was installed from Steam)

Open Terminal and paste in the following:

cd ~/Library/Application\ Support/Steam/SteamApps/common/Starbound/ && ./osx/asset_unpacker ./assets/packed.pak ./assets/unpacked

If the terminal seems to freeze up, that's ok. It'll take a minute or two for the script to run, depending on the speed of your computer.

The command above will navigate to the directory of the Starbound game files, run the built-in asset_unpacker, and store the unpacked files in the game file directory.

There are two ways to get to this folder:

  • Open Steam, right-click Starbound, click "properties", and select "Local Files", then "Browse Local Files".
  • In Finder, press Command+Shift+G (or select Go > Go To Folder in the menu bar), then paste in the following path:

~/Library/Application\ Support/Steam/SteamApps/common/Starbound


Open the terminal and type:

cd ~/.steam/steam/steamapps/common/Starbound/linux/ && ./asset_unpacker ../assets/packed.pak ../unpacked

After it finishes, you can find the unpacked resources at ~/.steam/steam/steamapps/common/Starbound/unpacked.

Step 2 - Setting Up Your First Mod

The Starbound/mods folder is where you're going to place .pak files or unpacked mods folders. Create a directory inside this.

Metadata File

The metadata file replaces the [MODNAME].modinfo file as of version 1.0 (Cheerful Giraffe, released July 22nd, 2016)[1]. It's an entirely optional JSON file that contains a set of entirely optional parameters. [2].

The metadata file can be named either _metadata or .metadata[3] and is placed at the root of a mod's folder.

(Note: Windows generally takes issue with any file that starts with a period. It's been suggested to either use _metadata for the filename, or name it .metadata. [4] Windows will strip the trailing period.

If you are using Steam for windows, you can upload a mod using the Mod Uploader Tool. This will automatically generate a metadata file for you. Simply click the normal play from Steam, and select the "Launch Mod Uploader Tool" and follow along with the instructions. It should be noted, however, that the uploader does not have fields for "requires", "includes", "priority" or "link", but will not harm any already contained in the file. Should these parameters be needed in a Steam upload, they will need to be manually added prior to uploading.

The metadata file contains general information about the mod, much of which will be displayed in mod's information section via the mod list on the Starbound title screen. (Note: parameter order doesn't matter, and that each parameter is optional; Starbound will load just fine without it. You could for example create a metadata file that only contained an author parameter, or a metadata file that included every parameter except a version number. If you don't need a parameter, don't include it. However, for the sake of releasing mods on Steam, it's strongly suggested you set the name, friendlyname, description and version parameters.

Here's an example of a metadata file that includes every parameter:
  "name" : "coolmod",
  "friendlyName" : "Cool mod",
  "description" : "This a cool mod!",
  "author" : "XxX-Cool mod Creator-XxX",
  "version" : "2.00 Alpha Gold",
  "link" : "",
  "steamContentId" : "000000001",
  "tags" : "Crafting and Building|Weapons|Armor and Clothes",
  "includes" : ["coolmodv1"],
  "requires" : ["anothermod", "coolmod2"],
  "priority" : 0
Entry Description
name The "behind the scenes" name that may be referenced by other mods. The requires and includes fields use this parameter.
friendlyName The name that'll show up mostly everywhere else.
description The description of the mod.
Type '\n' for a new line, and escape quotations with a \, such as
"description" : "This mod is \"cool\", if you know what I mean.\n:)"
author The author of the mod.
version The version of the mod.
link An URL that links to the mod. (Steam Workshop URL, Chucklefish Forum, Github,, etc)
steamContentId Each Steam workshop item has a unique ID. The Mod Uploader Tool available with Starbound's Steam version will fill this in automatically. Can be quoted (string) or not (number). If the original metadata file is lost, future uploads of a previously uploaded mod will fail unless metadata with a valid ID is provided or the name of the mod is changed; the ID for any workshop item can be found in that item's workshop page URL.
tags The workshop's tags this mod is classified as that steam uses. The Mod Uploader Tool offers a list of tags to select from.
includes A JSON list of mod names that will be loaded immediately before this mod, regardless of their priority value. If a listed mod does not exist, it is ignored.
(Note, this parameter name was poorly chosen and is confusing. It does not indicate that the mod contains or replaces the listed mods.)
(Remember that any parameter is optional! Don't add this if you don't need it!)
requires A JSON list of mod names that will be loaded immediately before this mod, regardless of their priority value. If a listed mod does not exist, the game will silently halt at startup, and an error message will be left in the game's log file.
(Remember that any parameter is optional! Don't add this if you don't need it!)
priority An integer value. If not present, the default is 0. In general, the lower the number, the sooner the mod will be loaded [5]. The base assets.pak has a priority of -9999.
Assume mod A has priority -10, mod B has declared no priority and therefore has a default priority of 0, and mod C has priority 15. Normally, the mod load order would be A, B, C. However, assume mod A includes or requires mod C. In that case, the load order becomes C, A, B.
(Note that Steam further alters the mod load order by scanning and loading workshop mods after all mods in the /mods folder have loaded).
(Remember that any parameter is optional! Don't add this if you don't need it!)

Step 3 - Modding


Reference Pages

If you did everything right, Starbound should load your new mod the next time you run it. If the game crashes, or your changes are not found in the game, check your starbound.log file.

Step 4 - Packing Your Mod

Before publishing your mod, it is better to pack it as a single <modname>.pak file. This process is recommended because it simplifies the installation (drop the file in the Starbound/mods/ folder), as well as the required I/O to read it. The alternative is to just put all the files into a zip archive.

To pack your mod, use the asset_packer(.exe) tool the same way you've used asset_unpacker to unpack your assets, or use ModPackHelper:

Windows/Linux with ModPackHelper

  1. If you haven't done it already, install modPackHelper (Simply drag script into Starbound\mods folder (and give executable rights for .sh))
  2. Select the "pack mods" action
  3. Choose the mod from the list (or set multiple choice with space, comma or semicolon)
  4. Press Enter. The mod is available in the Starbound/mods/ folder as <modname>.pak.

Step 5 - Publishing

Only one thing left to do - publish your mod! To do this, go to the official modding forums, select "add mod" in the upper right hand section, select the category of your mod, fill out the information form and hit save. It is that easy. The Steam version provides an utility to pack and upload mods to the Steam Workshop directly (and can also generate your _metadata file).

There are other places mods can be uploaded, or you can just share it with friends. What you do with your mod is up to you!

External Links

Quick Navigation

  2. The | Suit, Jul 22, 2016
  3. The | Suit, Jul 22, 2016
  5. Mod Load Order, 07 Aug 2020