Modding:Modding Basics

From Starbounder - Starbound Wiki
Jump to: navigation, search

Quick Navigation

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, and optionally, for easier packing and unpacking of mods and assets, ModPackHelper (available for Windows and Linux). Do not use a word processor such as MS Word instead of a text editor. Also do not use the basic notepad.exe, as it does not support UNIX line endings. Only UTF-8 is supported, other encodings are likely to cause crashes.





To prevent new modders following misleading, outdated guide, at the moment most of the content below should be ignored.

It is advised to read the Unofficial Modding E-book instead, available on Chucklefish Forums.




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.

First navigate to your Starbound directory and locate the asset_unpacker for your OS:


Warning! Following the instructions after 1.0.0 release will cause problems with starting your game, move the folders out of the asset folders before starting starbound. asset_unpacker.exe is found in the Starbound/win32/ folder. However, it cannot be run simply by double-clicking. Instead, there should be a file called unpack_assets.bat in the same folder. If you do not have that file, open your text editor and enter the following:

@echo off
echo Unpacking ..\assets\packed.pak into ..\assets\unpacked\
echo This may take a long time.
start /wait /min .\asset_unpacker.exe ..\assets\packed.pak ..\assets\unpacked
echo Done.

Save this as unpack_assets.bat (not .txt!) inside the Starbound/win32/ folder. Double-clicking that unpacks your assets to Starbound/assets/unpacked/ by default.

Note - If you need to unpack again, delete that folder first, as the unpacker can have trouble unpacking to an existing folder.

Windows with ModPackHelper

  1. Download the latest version of ModpackHelper
  2. Extract the zip in your Starbound/giraffe_storage/mods/ folder
  3. Double click on the ModPackHelper_vx.x.bat
  4. Choose action 0.
  5. Wait for success message.


Right click on and select "Show Package Contents". Next, locate your packed.pak file under Starbound/assets/. Finally create a new directory for the unpacked files, for example Starbound/assets/unpacked/.

Now open your command prompt window and enter first the location of asset_unpacker, then the location of packed.pak, and lastly the directory you want to unpack it into. Let the script run. When it finishes, you should see a long list of files and folders in the location you chose.

Linux with ModPackHelper

  1. Download the latest version of ModpackHelper
  2. Extract the zip to your Starbound/mods/ folder
  3. Open a Terminal Emulator
  4. Navigate to your Starbound/giraffe_storage/mods/ folder:
cd /<your_path>/Starbound/giraffe_storage/mods/
  1. Set executable permissions for the scripts:
chmod +x ModPackHelper_*.sh
  1. Run the .sh script
  1. Choose action 0.
  2. Wait for success message.

Step 2 - Setting Up Your First Mod

_metadata file

This file is entirely optional.

Now that you have a file to tell the game that the mod will load the contents inside, the next step would be to add a _metadata file. The _metadata file is to tell the user who installed the mod the general information about the mod when they check the mod list on the Starbound title screen. This will list the username, the version of the mod, the link to the mod's page and a description of the mod along with who made it.

Inside where you put the .modinfo file, have a file called "_metadata", not "_metadata.txt"! Or else it wont work.

Open the file inside a text editor and paste this information in:

 "version" : "0.00",
 "friendlyName" : "MODNAMETITLE",
 "link" : "",
 "steamContentId" : "",
 "name" : "MODNAME",
 "description" : "This a cool mod!",
 "author" : "NAME"
Entry Description
version The version number of your mod.
friendlyname This is the name that will show up in the mod list menu.
link A URL that links to the mod.
steamContentId This is the unique id that steam uses, if you are not putting the mod up onto steam's workshop, leave this blank.
name (If anyone knows what this argument is for, please update this!)
description This is the description of the mod. type '\n' for a new line.
author The author of the mod, put in your name here.

Step 3 - Modding


Reference Pages

Step 4 - Final Notes

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 5 - Packing your mod

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

To assemble your mod into a modpak, follow bartwe's post or use ModPackHelper:

Windows/Linux with ModPackHelper

  1. Follow what is described in #Step 1 - Unpacking Assets (Depending on your operating system).
  2. When script is launched, choose action 1].
  3. Then select the mod you want to pack (If your mod folder does not contain a .modinfo file, it will not show as a choice).
  4. Press Enter. The mod is available in the Starbound/giraffe_storage/mods/ folder as <modname>.modpak.

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

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!

Step 7 - Advanced Topics

So you think you're a modding genius, eh? Well, if you're bored with the current Stable version, you can try your hand at modding on the nightlies with cutting edge features so sharp you'll need to wear some really thick gloves or something.