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

Windows

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.

Notes

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

Mac

(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

Linux

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). It's an entirely optional JSON file that contains a set of entirely 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. 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" : "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 is used by other mods. The "requires" and "includes" 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, 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	Any mods listed here will be loaded before this mod (regardless of their priority value), if they exist. (remember that any parameter is optional! Don't add this if you don't need it!)
requires	Any mods listed here will be required, will be loaded before this mod (regardless of their priority value), and the game will error at startup if these mods aren't present. (remember that any parameter is optional! Don't add this if you don't need it!)
priority	The lower the number, the sooner it'll be loaded. The base assets.pak has a priority of -9999. This value will be ignored if another mod has this mod in it's includes or requires, and will be forced to load right before that other mod's priority value. (remember that any parameter is optional! Don't add this if you don't need it!)

Step 3 - 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 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

• Chucklefish Forums - Starbound Modding
• Chucklefish Forums: How to successfully pack and unpack .pak files
• Chucklefish Forums: Getting started in making mods for Starbound
• Chucklefish Forums: ModPackHelper
• Chucklefish Mods: Unofficial Modding Ebook 2.0
• 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