295 ratings
Skittles' Guide to Making your Own Race
By DrPvtSkittles
I will guide you through the ins and outs of making a custom race in Starbound. W.I.P.
So you've decided to make your own race, and you don't know where to start. This guide aims to detail everything you need to know to get your race off the ground.

Currently a W.I.P. Please leave a comment for any topic you wish for me to touch on.

Put your race mod into your 'mods' folder when you are ready to test it.

This guide is current as of April 2022
!Important change to template!
The templates have been updated

Fixed the treasurepools.patch file
Removed the items that are found in the starter treasure, and replaced it with the line

{"pool" : "starterTreasure"},

This allows for other mods to tweak the vanilla starter treasure, and have it apply to the custom race.

I am sorry for aaaaaaaaaaaaaaaaaaaall of the race mods that have my error in them >_>

Thank you to RicoWan for pointing out and helping me fix this problem.

Removed some files from Basic
Removed boosterflame.animation and boosterflame.lua

They were removed the advanced template a long time ago but I forgot to remove them from basic.
Cheat Sheet
So you are confused as all hell and want me to give you the gist of it.

First, grab yourself a graphics program and a word editor.

Download the template of your choice and extract it (you can use ) into your mods folder.

Read the read me and do as instructed

Choose a name for your race. USE ONLY LOWERCASE (no capital letters) WHEN NAMING YOUR RACE IN THE BAT FILE.

You can find the sprites for your race humanoid\YOURRACENAME

If you need a template to understand how to go about this
Handy Dandy Programs
Good news! Starbound modding only requires any basic graphics editor (that can create transparent pixels and save in .png) and any text editor.

Free Graphic programs:
paint dot NET[]

Great Graphic editor if you are willing to spend $15
Aseprite[] - Or you can compile for free from the open source code - Cheers Azure Fang

Free word editors designed for coding
Sublime Text[]

Browser based editors

File compressing
PNGGauntlet[] - Shrinks .png file sizes.
7Zip[] - To unpack and pack any file in general.
PAKit[] - To pak and unpak starbound mods. (Note, do not pak a mod if you are uploading it to steam, it will do it for you).

Free Audio Editor

Making Gifs
The Template
I have currently created 2 templates for race making. One basic and one advanced.

Basic includes:[]
Respawn Cinematic
Hair and Body parts
Basic Sword
Ship and Ship assets
Sfx Hurt sounds
Shiplocker Treasure Pool

Advanced includes[]
All Tier armours - various races
Race Spawner
Custom ship pet - Fennix
Penguin Merchant (craft at inventors table)
A simple particle effect.
Hat with the effect added to it. (purchase at merchant)
Race Spawner (purchase at merchant)
Blank banners (purchase at merchant)
Basic furniture with your race's colony tag (purchase at merchant)
+All what is in the basic version

Prefer nexus mods?

Character Extender
You can't see your custom race without one. I prefer to use Kawa's xbawks-mode character []
Naming your race
For the purpose of this guide, I will stick to using the advanced template throughout. Once you have downloaded it from the website of your choice you will notice its in .7z format. This format compresses the file to a smaller size than standard .zip which is why I've chosen it. To extract this file you will need 7zip[], its free, open source and can open many different compressed files.

After extraction, place the folder in your 'mods' folder, that is located in your 'Starbound' folder.

Chucklefish doesn't like bat files:

To turn the ADVANCED_RACE_TEMPLATE_EASY_SETUP.txt into a bat file open it up in your word editor, go Save As, then Save As Type, change that to All Files. Then change the name to BASIC_RACE_TEMPLATE_EASY_SETUP.bat


Now double click to run it.

Now double click on the file called ADVANCED_RACE_TEMPLATE_EASY_SETUP.bat
The .bat file (short for batch) is Windows only, and will not work for Linux and Mac users. You will need to source a program that will allow you to change 'skadvtest' to your race name.

Picking a name
The .bat file will ask you to choose a name longer than 3 characters. Bare in mind this name is NOT visible to the public, its for the use of Starbound, so it MUST be unique. Avoid using names like Mouse or Robot, that might be something someone else may pick. Since this name is not seen, you could pick the name 'asjuajdh', for the 'proper' then in game the race shows up as being called the Teletubbies.
Do NOT use uppercase (capital letters), spaces, or any character either than the standard a-z english alphabet. Not adhering to this standard may make your race not show up in character select.

For this example I will use the name 'myfirstrace'. After picking your name, press enter and wait for the .bat to finish.

Press any key or close the window.
Okay now let's really name the race
Where does my race name actually show?
Navigate to your species folder then myfirstrace.species *Note, when I use 'myfirstrace' in this guide you would go to the name you chose when you used the .bat. Also the text program featured in these
screenshots is Notepad++) .

As you can see, here we can choose what to put as a description, and where to name our race in character select.

Note: Write your name in uppercase as that is what the vanilla races use.

For this race, I will label them Cyclops, however the file name will remain as myfirstrace. This is to illustrate where you can put the "real" name of the race, vs where it needs to be its unique file name.
Dissecting the species file
This is the most important file in your race, and chances are, if your character icon in race select doesn't show, you've mucked up something here. (don't ask me why this happens :P I think its just a coding quirk)

"kind" : "myfirstrace", - this needs to be the name you used in the batch file.

"title" : "myfirstrace", - not sure where this shows, but it can be capitalized unlike "kind"

"subTitle" : "O2", - I think this is unused now

"description" : "Taste the rainbow!" -as shown above, it's the description of your race, in the character creator.

"nameGen" : [], - the file(s) that will be used to generate your names

"ouchNoises" : [], - the location of the file your race uses when it takes damage

"charGenTextLabels" : [], - straight forward. Note that the race is always in UPPERCASE

"skull" : "/humanoid/myfirstrace/dead.png", - used when people play hardcore, its the death icon.

"effectDirectives" : "?replace=FEFFFFFF=FFFFFFFF?replace=9bd4ffFF=ffea63FF?replace=31a6ffFF=f5bc00FF", - the most over looked item here. The start of the beam up, and the end, the colour is defined here. Change the last colour value, the one before the question mark.

"defaultBlueprints" : { - This goes from Anvil to Special. These are the recipes that will be exclusive to your race. No other race can craft them. Unless you patch them into 'player.config.patch'.

Tricky Stuff
They MUST be written as they are, with the capitals where they stand. If included they have either a true or false value.

Back up your mod before tinkering with this, as your mod may not start with the wrong line included.

Avian. Needs “altOptionAsUndyColor” enabled. Makes the facial mask use the undy colour.

Apex, Floran, Glitch, Humans, Hylotl. The alternate slider changes the colour of the undies (red bits).

Floran, Glitch and Hylotl. Needs “headOptionAsHairColor” enabled. The alternate slider changes the 'undy colour', commonly seen as the red colour on the sprites. It allows for the hair sprites to utilise the red/undy colour as an additional colour for the hair.

Avian. Alternate slider changes facial mask image.

Avian. Facial mask will use the colours listed in the body section of the specie file.

Glitch, Hylotl. The body will use colours listed in the hair section of the specie file.

Floran. Glitch. Humans, Hylotl. The head slider will change the hair colour. If this is not included, then the hair colour will use the same colour of the body.

Apex, Avians. The head slider changes 'facial hair'.

For simplicity I will just talk about the male (as I will just end up repeating myself).
"name" : "male", - I don't know if you can change the name of this, and I've not tried.
"image" : "/interface/title/myfirstracemaleico.png", - the image that represents the male gender in the character creator.
"characterImage" : "/interface/title/myfirstracemale.png", - the neat little portrait of your male race.
"hair" : [], - you can name your hairs whatever you want, they are listed here.
"shirt" : [], - the tops you can choose from in character select.
"pants" : [], - the pants you can choose from in character select.

"facialHairGroup" : "",
"facialHair" : [],
"facialMaskGroup" : "",
"facialMask" : []

This is used by Apex and Avians for their beards n facial fluff. If you want to tinker with facial stuff, see the above with the 'Tricky stuff'. I encourage you to unpack the assets (see below) and check out the Avians and Apex to see how they work.

For information about 'bodyColor' hex codes and what not, see below.
Sprite Guide
Where to start?

Skittles' Template Goodies[]

Download the .7z file on the first post. In it are .psd files AND .png files that should cover all of your race making and armour making needs.

Colour mapping

Note, colour highlight effect is not found in notepad++, I have made this in my image editor

I have highlighted what each colour each code is. The first colour is what is on the sprite, and the second colour is what it will be changed to.

Most graphic programs are able to give you the hex code for the colour you wish to use, if not you can use HTML Color Codes[]

For this guide I will bring one of the rejected beta races to life.

That big eyed race looks fun!

Here is what the new head looks like after changing the colours to the same as the human's body palette.

In game. How fun!

Now lets unpack some assets before we get too stuck into things.
Unpacking the Assets
It is important as examining the vanilla races will help you learn how to make your race in the way you wish. For example if you wish for your race to glow you can study the Novakid's species file to see how its done.

"statusEffects" : [],
"humanoidOverrides" : {
"bodyFullbright" : true

This video details how to unpack the assets.

The gist is that in your starbound folder save a file as a .bat with:

"G:\SteamLibrary\steamapps\common\Starbound\win32\asset_unpacker.exe" "G:\SteamLibrary\steamapps\common\Starbound\assets\packed.pak" "G:\SteamLibrary\steamapps\common\Starbound\assets\unpacked"

Replace the the directory location to where your files are.

The Ship
Sprites for the ship are found in 3 places.

cinematics/story/smallship - This is the ship as it escapes earth in the beginning.
objects\protectorate\objects\protectorateship - The ship you see and the end of the Protectorate Tutorial level.
ships\myfirstrace - Where your Tier 1 to Tier 8 sprites are.

For each Tier, there are 3 images for it.

This dictates the physical space and spawned items of the ship. (I have enlarged it here for clarity).

Each colour represents either a block or an object and this is defined in your blockKey.config. This coloured block map deelie is 1/8th the size of your ship. If we take a gander at the 4th thing in the blockkey that talks about the ship wall n locker and starter treasure.

"value" : [0, 255, 0, 255], that’s the colour, [red, green, blue and opacity].

"foregroundBlock" : false,
“backgroundBlock" : true,

I *think* this is stating whether or not this object or block will sit in the foreground, background or both. Tbh I don't know why both are listed, when I don't recall seeing any that has both as true or both as false.

"backgroundMat" : "apexshipwall", the material that will be in the background.

"flags" : [], Right now, I have no idea. Lol

"level" : 0.5, dunnno… ha.

"unbreakable" : true, can you break it, yay or nay?

"objectResidual" : true, dunno >_>

The sprite of the ship

The same sprite, however what ever is opaque will be darker than what is transparent.

For each Tier there is a structure file. This has crewsize, capabilities ("teleport", "planetTravel", "systemTravel") and what images are used.

Some important things to note, if you take a gander at how ships expand they always ADD to the current ship and NEVER replace anything. If you try it any other way you will muck things up.

I don't know why (although I have a theory) moving ship items around, when you think there’s space, will cause them to not show up. My theory is that while an item has a visual space, it has a usable space so if you put your chair too close to your ship fuel indicator, one of those wont show… but that is just a guess.
Adding multiple races to one mod
While you can grab the contents from one renamed template, and slap it into another, there will be some files you will need to manually edit to include all the races in your mod.

ai.config.patch [ai]
charcreation.config.patch [interface\windowconfig]
player.config.patch [in the main folder]
protectorateship.object.patch [objects\protectorate\objects\protectorateship]
quests.config.patch [quests]
shiplocker.treasurepools.patch [treasure]
universe_server.config.patch [in the main folder]
All .patch files in your dialog folder
What should I have done before my first release?
There are some things you should have in your mod before your first release, as adding/changing them later can be a bit of a pill.

PNGGauntlet[] - A great program for compressing the file size of your .png files. I cannot stress how well this works, and I have had mods been halved in size.

The most important of all of these is the name that you chose in the .bat file. If you change that after your first release, then Starbound will see your update as a separate race to the previous version.

The ship. Changing this later can cause player's ships to muck up and become corrupted, unless its just a simple sprite change, and you aren't changing the physical structure of the ship.
Something is wrong! How do I fix it? First step is to check your log. You will find it in your Starbound folder, in 'storage'. There are 6 logs, the ones numbered 1-5 are older logs. The one we want is the non-numbered one on the top.

Open it up and do a word search for the word error, too easy!

Things to keep an eye peeled for

I can't see my race! - Do you have a character extender?[]

My race's icon is missing! - Chances are this is not a problem with your icon or icon folder. Check your log, and try to take a look back at the last thing you have been working on before your icon disappeared. The most common problem is that you have used uppercase letters when naming your race using the bat file. Your file structure needs to look like Starbound\mods\YOURMOD. If you then put your mod into an additional folder, starbound will not be able to find things it needs to find. If this has not worked, it is possibly something you have done in your species file.

[Error] Application: exception thrown, shutting down: - That line is usually found at the bottom of the log, and it tends to be the culprit thats causing your game to crash.

[Error] Could not load recipe /recipes/anvil1/armor/tier1/myfancyclothing: (ItemException) No such item 'wovenfabric' - Oops, looks like your recipe lists an item that doesn't exist. Perhaps you meant 'fabric'.

[Error] Object myfancybed defined twice, second time from /objects/beds/myfancybed .object - Oops, two of your items have the same itemname. One must be changed.

[Error] Exception caught loading asset: /recipes/yummyfood/yumbikkie.recipe, (AssetException) Could not read JSON asset /recipes/yummyfood/yumbikkie.recipe
Caused by: (JsonParsingException) Error parsing json: bad array, should be ',' or ']' at 9:50
- This says in your recipe, at line 9, character 50 you have made a mistake and it should be a comma or bracket.

Check for those pesky commas
Go to objects\myfirstface\myfirstracemerchant\myfirstracemerchant.object
See the item list

"items" : [
{ "item" : ["bomb", 5] },
{ "item" : "myfirstracekittyhead" },
{ "item" : "myfirstracebannerlarge" },
{ "item" : "myfirstracebannersmall" },
{ "item" : "myfirstracewoodchair" },
{ "item" : "myfirstracewooddoor" },
{ "item" : "myfirstracewoodenbed" },
{ "item" : "myfirstracewoodendesk" },
{ "item" : "spawnermyfirstrace" }

See how the last item does NOT have a comma. This is important. If you add a comma there, your game will not start. If you remove a comma from one of the items above, your game will not start.

For more information see my guide on troubleshooting HERE
Uploading to Steam
Double click on Starbound in your games list.

Choose 'Launch Mod Uploader Tool'.

Press Select Mod Directory and navigate to where your mod is, and select that folder.

Replace the information seen here with your own. Do not fret if what you have put in your description isn't perfect, because stage 2 is where we will refine the mod listing.

Tick the boxes to the right that make sense for your mod. Select a preview image (icon) for your mod. This is the only place where you can do this.

Write a brief description if your mod. You can change this after you submit this, and before you make the mod public. From there you can:

Edit title & description
Add/edit images & videos
Add/remove Contributors (note, you need to be friends with the person)
Edit Link
Allow Comments


Add/Remove Required Items (add mods that your mod requires, for species this may be a character extender)
Add/Remove Required DLC (not useful for Starbound)
Change Visibility (this starts off as hidden, you can make this unlisted, friends-only or public)
Uploading Elsewhere
If you choose to upload your mod elsewhere, you will need to edit the metadata file manually.

This file is found in your mod's main folder. It is simply called metadata.

It should have:

"tags" : "Species",
"author" : "DrPvtSkittles",
"description" : "Advanced Template to create your own race.",
"friendlyName" : "Skittles Advanced Race Template",
"link" : "",
"name" : "Skittles Advanced Race Template",
"path" : ".",
"steamContentId" : "",
"version" : "1"

tags: this shouldn't need to be changed, as your mod should fall under species :P
author: your name
description: a brief description of your mod
friendlyName: name of your mod, it doesn't have to be unique.
link: usually the steam link of your mod. I am unsure if you can put any link there
name: this needs to be unique
path: i... don't know. ha
steamContentId: used by steam, each steam mod has its own unique number
version: you can put anything here, letters or numbers. I like to start mine at 0.1.

Typically you will need to zip or pak your mod before uploading. I prefer to zip, so other people can easily learn from my work (or god forbid I vanish from the modding scene and my mods won't be locked to a certain Starbound release). If you wish to pak your mod, I recommend using PAKit . Read their guide for more info.
You will want to take screenshots using .png as the jpeg artifacts really show up on pixel art.


In steam, go to 'Settings', then 'In-Game', then tick '[When a screenshot is taken] Save an uncompressed copy'. You will be prompted to choose a folder for screenshots (it will be different to where the others are kept). In this new folder .png versions will be saved.

Ahh much better!

"But Skittles, how can I insert pictures into my descriptions?" I hear you ask.

Lets grab some mods

Greenscreen Blocks Can make your life a little easier. Read the mod desc on information on how to use them.

Extra Zoom Levels So we can zoom all the way out to 1x.

While in Starbound, in the chat type
/admin (press enter)
/fullbright (press enter)
/spawnitem greenscreenblock 600 (press enter)

Build your green platform and take a screenshot (I prefer to use at x1 and resize later).

Open it up in your graphics editor and select the green colour and remove it.


Upload your image to your mod.

Click on the image in your showcase, then click on the bigger image to bring up the original file, then right click and do 'Copy image address'.

In the description of your mod paste the image link between [img][/img]

It will look similar to:

If you have copied the right link, it should show up as a nice little embedded image.

For examples check out
The Advanced Template

How about a gif?

Making a smaller or taller race
The woggles are a smaller race.

In their species folder they have a custom config they use in place of the vanilla humanoid.config. It is enabled by having the line "humanoidConfig" : "/species/woggle.config", in their species file. The humanoid/woggle folder has custom frame files.

I haven't played around with making a smaller race myself so I can't go into detail about exactly what to do. My suggestion to you would be to start adding what I've listed, and tweak it.
Other useful information
Here I will list resources that may not be about race making, however useful for any aspiring modder.

Unofficial Modding Ebook 2.0 SB v1.05 []

Lists of Block IDs that have been taken[]
Starbound Paint dot net palette. Copy contents into notepad and save as Starbound_Palette.txt [CREDIT] - Nebulox
; Palette File
; Lines that start with a semicolon are comments
; Colors are written as 8-digit hexadecimal numbers: aarrggbb
; For example, this would specify green: FF00FF00
; The alpha ('aa') value specifies how transparent a color is. FF is fully opaque, 00 is fully transparent.
; A palette must consist of ninety six (96) colors. If there are less than this, the remaining color
; slots will be set to white (FFFFFFFF). If there are more, then the remaining colors will be ignored.

Starbound Swatches
In both .aco (for photoshop) and .ase (for other adobe products)
To do
This guide is very W.I.P. What is here should be enough to get you started. Please comment below and let me know what needs to be added to this mod.

To expand on
mask.png for head items determines what hair/facial bits will be seen or hidden. Full opacity for showing all, zero opacity to hide.
< >
DrPvtSkittles  [author] Jul 4 @ 8:35am 
The species file has what you are looking for.

Read up on the 'dissecting the species file' for more info.
Cobalt Tavin Jul 4 @ 8:21am 
When I change the ears on my species it will change the shirt instead
and the shirt changes the pants and the pants slider does nothing

Where are these variables located so I can edit them?
DrPvtSkittles  [author] Jun 4 @ 9:17pm 
Weeeeell I didn't write it so I dunno how to fix it
warpnarget Jun 4 @ 3:19pm 
so uh the .bat does a funny when run through wine
Animation Jack (AJ) May 18 @ 1:02pm 
I'll take a closer look at everything. if I fix it I'll probably say something.
DrPvtSkittles  [author] May 18 @ 12:50pm 
Animation Jack (AJ) May 18 @ 12:34pm 
they do spawn when you use the "Spawner" but that isn't an actual settler.
Animation Jack (AJ) May 18 @ 12:20pm 
whats funny is they don't show up on the ship either its weird.
DrPvtSkittles  [author] May 18 @ 12:19pm 
i know they will show up in the ship >_>
DrPvtSkittles  [author] May 18 @ 12:19pm 
check the tags