Modding:Basics

Work In Progress!

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 INVADA on 2025-04-30 19:12:07.

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

Unpacking The Assets

Before you start modding you will first need the unpacked assets as a reference. All of Starbound's assets are stored in Starbound/assets/packed.pak in the.pak format, and need to be uncompressed before you can view or use them properly. This step will NOT remove or change your packed.pak file. Modifying the unpacked assets will not affect your game.

Windows

Current as of Version 1.3.1, June 27th, 2017

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

Notes

• If purchased from Steam, the location of the main Starbound directory folder typically looks like Steam\steamapps\common\Starbound
• The text typed into Command Prompt/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.

Mac (Steam)

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

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

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 ~/Library/Application\ Support/Steam/SteamApps/common/Starbound

Linux

Open 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: Modding

Tutorials

• Editing Vanilla Files

Reference Pages

• Data Assets
• New Custom Material ID Registration - if you're going to add new blocks, read this first!
• New Custom Liquid ID Registration - if you're going to add new liquids, read this first!
• Behavior Trees

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 3: 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). It's an optional JSON file that contains a set of optional parameters. .

The metadata file can be named either _metadata or .metadata 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. 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. However, you should note 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 in the Starbound mod list 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, if you upload mods to Steam, you're strongly suggested to set the name, friendlyname, description and version parameters.

Here's an example metadata file that has every parameter:

{
  "name" : "coolmod",
  "friendlyName" : "Cool mod",
  "description" : "This a cool mod!",
  "author" : "XxX-Cool mod Creator-XxX",
  "version" : "2.00 Alpha Gold",
  "link" : "http://example.com/coolmod",
  "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 mod description. 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 mod author.
version	The mod version.
link	An URL that links to the mod. (Steam Workshop URL, Chucklefish Forum, Github, yourwebsite.net, 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 . 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, if mod A includes or requires mod C, 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 4: Packing your mod

Before publishing your mod, packing it as a single <modname>.pak file is recommended. This simplifies installation (drop the file in Starbound/mods/ folder), as well as the required I/O to read it.

The alternative is to just put all the files into an 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!

Chucklefish

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.

Steam

The Steam version provides an utility to pack and upload mods to the Steam Workshop directly (and can also generate your _metadata file).

Other Services

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

External links

• Chucklefish Forums - Starbound Modding
• Chucklefish Forums: How to successfully pack and unpack .pak files
• Chucklefish Forums: Getting started in making mods for Starbound
• Chucklefish Mods: Unofficial Modding Ebook 2.0
• Chucklefish Forums: ModPackHelper
• Youtube: Starbound Tutorial, From Unpacking to Distribution and Everything Inbetween v1.2+
• Chucklefish Forums: Browse the "tutorial" tag for more diverse and in-depth tutorials.

Quick Navigation

Modding

Portal - Basics - JSON - Lua - Assets - Guides

---

Home - Helping Out

Modding