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 Jzpelaez on 2017-08-02 14:51:20.

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

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 since version 1.0 (Cheerful Giraffe, July 22nd, 2016). It is JSON-formatted and is entirely optional. It can be named either _metadata or .metadata (Note: Windows won't allow .metadata unless you add a . at the end) and is placed at the root of a mod's folder. The Mod Uploader Tool provides a GUI to edit it.

It contains general information about the mod which will be displayed in the mod list on the Starbound title screen, informations the game uses to determine load order if needed, and informations the Mod Uploader Tool uses if needed. Note that parameters' order doesn't matter, and that each parameter is optional; Starbound will deal without it. You could for example only fill the author field and not put the rest, or put everything but the version number. If you don't need a parameter, don't include it.

Here's an example of a metadata file that includes every parameters:

{
  "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,
  "includes" : ["coolmodv1"],
  "requires" : ["anothermod", "coolmod2"],
  "priority" : 0
}

Entry	Description
name	The "behind the scenes" name that is used for other mods' "requires" and "includes" parameters.
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.
steamContentId	The workshop's unique id that steam uses. The Mod Uploader Tool available with Starbound's Steam version will fill this automatically.
includes	Any mods listed here will be loaded before this mod, 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, and the game will crash at startup if those 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. (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
• New Custom Liquid ID Registration

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