Starbound

Starbound

35 ratings
Modding: Planet Guide
By Ceterai
This guide will tell you how to create and customize planets.
WEBSITE[ceterai.github.io] | SUPPORT ME[buymeacoffee.com]
   
Award
Favorite
Favorited
Unfavorite
Preface
For the sake of this guide the planet we will create will be called my_cool_planet for a mod called my_cool_mod.

Note, that in order for your planet to spawn ingame, you will have to explore new areas of the universe, or, even better, create a new one.

This guide will not tell you how to create a biome. If you want to learn how to do that, you can read this guide:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=2128333589
This guide will not tell you how to create or add weather to the planet. If you want to learn how to do that, you can read this guide:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=2608845860
This guide assumes you already know how to unpack Starbound game files (images, textures, icons and scripts). If you don't, here are helpful links:
https://starbounder.org/Modding:Basics#Step_1_-_Unpacking_Assets
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=1161535874
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=2145917164
Graphics
First of all, we need to have three things:
  1. Planet base colours and dynamics;
  2. Planet horizon textures and masks;
  3. Planet icons.

Of course, if you don't want to draw these things, you can use stuff from already existing planets. If you deside to do that, you will have to reference them accordingly in other steps.

1. Base colours & dynamics
Here we design how your planet will look on the celestial map.
Base colours
These are just circles filled with a certain colour, that are applied to different layers on the planet.

If you want to create your own base colours, you should create them on a specific path:
"my_cool_mod\celestial\system\terrestrial\biomes\my_cool_planet"
And call them "maskie1.png", "maskie2.png", etc.

Note: you can use different paths and names, but for the sake of this guide I will use names and paths similar to the ones used by original Starbound resources.

Example for the forest planet:
As you can see, all colours of the forest planet except water are here.
Similarly, when creating base colours for your planet, you should exclude any liquids. We will add them separately.


Dynamics
These are basically all possible masks, to which our base colours will be applied.

Of course you can create your own, but I would highly recommend just going with already existing ones, for example here are temperate dynamics:
If you want to use them, you don't need to copy them anywhere, just skip this step.

But, if you want to create your own dynamics, you can create them on a specific path:
"my_cool_mod\celestial\system\terrestrial\
dynamics\my_dynamics
"
And call them "0.png", "1.png", etc.
Again, you can use your custom path, but I highly recommend this one.

2. Horizon textures & masks
Here we design how your planet will look up close while you're on your ship.
Horizon textures
It's hard to explain how these should look, so let's just look at an example for forest planets:
If you want to create your own horizons, you should create them on a specific path:
"my_cool_mod\celestial\system\terrestrial\horizon\textures"
And call them "my_cool_planet_l.png" and "my_cool_planet_r.png".

Again, if you want to use already existing ones, you don't have to copy them.

Horizon masks
These are all possible masks, to which our horizon textures will be applied.

You can create your own, but I would highly recommend just going with already existing ones, for example here are temperate dynamics:
If you want to use them, you don't need to copy them anywhere, just skip this step.

But, if you want to create your own dynamics, you can create them on a specific path:
"my_cool_mod\celestial\system\terrestrial\
dynamics\my_masks
"
And call them "0_l.png", "0_r.png", "1_l.png", "1_r.png", etc.
Again, you can use your custom path, but I highly recommend this one.

3. Icons
These are two almost similar icons that will represent your planet in user interface.
If you need examples, they are located on these paths:
"packed\interface\bookmarks\icons", "packed\interface\cockpit\planets"
There they are:
In this case it is absolutely important that you place them on their respective paths:
"my_cool_mod\interface\bookmarks\icons", "my_cool_mod\interface\cockpit\planets"
Don't forget to call them after your planet, like "my_cool_planet.png".
Celestial config
Let's put our graphics to use.
Create a file called celestial.config.patch in the root folder of your mod, like this:
"my_cool_mod\celestial.config.patch"

This is a json-patch file. If you're not sure how they work, you can checkout this guide:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=2124444255

Put the following code in this file:
[ { "op" : "add", "path" : "/terrestrialHorizonGraphics/my_cool_planet", "value" : { "baseImages" : "/celestial/system/terrestrial/horizon/textures/my_cool_planet_<selector>.png", // if you desided to use already existing horizon textures, change my_cool_planet to the name of the according planet. If you placed your horizon textures on a different path, you should also change it here. "maskTextures" : "/celestial/system/terrestrial/horizon/masks/temperate/<mask>_<selector>.png", // you can change "temperate" to any existing or your custom horizon masks. "maskRange" : [1, 25], // how many masks there is in your chosen folder (25 for temperate). "maskPerPlanetRange" : [3, 3] } }, { "op" : "add", "path" : "/terrestrialGraphics/my_cool_planet", "value" : { // same tips here "baseImages" : "/celestial/system/terrestrial/biomes/my_cool_planet/maskie<num>.png", "dynamicsImages" : "/celestial/system/terrestrial/dynamics/temperate/<num>.png", "dynamicsRange" : [1, 30], // 30 for temperate. "baseCount" : 5 // how many base colours did you create? } }, // where will your planet spawn? { // this will spawn your planet as a Tier1 planet. "op" : "add", "path" : "/planetaryTypes/Tier1/baseParameters/terrestrialType/-", "value" : "my_cool_planet" }, { // this will spawn your planet as a Tier2 satellite. "op" : "add", "path" : "/satelliteTypes/Tier2/baseParameters/terrestrialType/-", "value" : "my_cool_planet" }, { // this will spawn your planet as a Tier1 satellite. "op" : "add", "path" : "/satelliteTypes/Tier1/baseParameters/terrestrialType/-", "value" : "my_cool_planet" } // you can add as much of these "spawn blocks" as you want. ]

Everything following two dashes (//) are comments and can be omitted.

Here's what we would get if we were to add another forest planet:
[ { "op" : "add", "path" : "/terrestrialHorizonGraphics/forest", "value" : { "baseImages" : "/celestial/system/terrestrial/horizon/textures/forest_<selector>.png", "maskTextures" : "/celestial/system/terrestrial/horizon/masks/temperate/<mask>_<selector>.png", "maskRange" : [1, 25], "maskPerPlanetRange" : [3, 3] }, }, { "op" : "add", "path" : "/terrestrialGraphics/forest", "value" : { "baseImages" : "/celestial/system/terrestrial/biomes/forest/maskie<num>.png", "dynamicsImages" : "/celestial/system/terrestrial/dynamics/temperate/<num>.png", "dynamicsRange" : [1, 30] }, }, { "op" : "add", "path" : "/planetaryTypes/Tier2/baseParameters/terrestrialType/-", "value" : "forest" }, { "op" : "add", "path" : "/satelliteTypes/Tier2/baseParameters/terrestrialType/-", "value" : "forest" } ]
Terrestrial worlds
Same as with celestial.config.patch, you will need to create terrestrial_worlds.config.patch in the root folder of your mod.
Put the following code there:
[ { "op" : "add", "path" : "/planetTypes/my_cool_planet", "value" : { "threatRange" : [3, 4], // any values from 1 to 6. [1, 1] means that your planet can only have threat level 1. [1, 6] means any level from 1 to 6. "layers" : { "surface" : { "primaryRegion" : [ "[b]biome_name_here[/b]" ], // this is a primary biome on your planet. "secondaryRegions" : [ "bioluminescence", "colourful", "hive" ], // any other biomes that can spawn on your planet. "dungeonCountRange" : [2, 3], // how many big dungeons can be on your planet? "dungeons" : [ // a pool of said big dungeons. You can find them in packed\dungeons. [1.0,"oasis"], [2.0,"hylotlcity"], [1.0,"floranvillagetower"], [1.0,"floranhutvillage"] ] }, "subsurface" : { // biome right under the surface [optional]. "primaryRegion" : [ "arborealunderground" ], "secondaryRegions" : [ ] // secondary biomes are also optional, even if the primary is set. }, "underground1" : { // layer 1 underground [optional]. "primaryRegion" : [ "ffspidernest", "luminouscaves", "ffcoppermine" ] }, "underground2" : { // layer 2 underground [optional]. "primaryRegion" : [ "ffhiveunderground", "colorfulcave", "luminouscaves" ] }, "underground3" : { // layer 3 underground (the deepest one before core) [optional]. "primaryRegion" : [ "zen", "ffhiveunderground", "shroomcave" ] }, "core" : { // custom core biome [optional]. "primaryRegion" : [ "core" ] } } } } ]
Again, if you want to make your own biome for this planet, here's a helpful guide.
Cockpit entry
Here we will set your planet's description and other stuff for the celestial map.

Create a cockpit.config.patch file on this path:
"my_cool_mod\interface\cockpit\cockpit.config.patch"

Put this code in the file:
[ { "op" : "add", "path" : "/visitableTypeDescription/my_cool_planet", "value" : [ // list of possible descriptions for your planet. "^#0055f1;Planet^white; description 1.", "^#0055f1;Planet^white; description 2.", "Planet description 3." ] }, { "op" : "add", "path" : "/planetTypeNames/my_cool_planet", "value" : "My Cool Planet!!!" // user friendly name. }, { "op" : "add", "path" : "/planetTypeColors/my_cool_planet", "value" : [0, 135, 255] // color of the user friendly name. } ]
That's it!
Conclusion
Sometimes when testing, your planets may appear oversized on the celestial map. If this happens to you, check the game log.

That is all I can share with you on this topic. I will expand it if I find/learn more about it.
If you need full planet examples, you will need to unpack game files. There's a number of Steam guides that tell how to do that.

I know that there are guides on this out there, but information in those that I found turned out to be somewhat outdated, which is why I made this guide.

Please let me know if I forgot or mixed up anything.
Thank you for reading!
24 Comments
Ceterai  [author] 2 Mar @ 12:21pm 
fixed, thanks! ^^
CookiesAndCream 2 Mar @ 10:13am 
super helpful guide bro, fyi for the "terrestrial worlds" patch you are missing a comma in the "subsurface" section just after primaryRegion and before secondaryRegion.
"primaryRegion" : [ "arborealunderground" ], <===
Ceterai  [author] 2 Apr, 2023 @ 3:04pm 
you can simply create a folder in <your-steam-path>/Starbound/mods/ and name it anything you want, any assets you add there will be picked up by the game

if you're wondering where to start, there are great resources out there that will walk you through the process, here's one for example: https://starbounder.org/Modding:Portal

specifically you might be interested in https://starbounder.org/Modding:Basics
danb108 2 Apr, 2023 @ 2:56pm 
how do I make the mod itself and the folder
Ceterai  [author] 30 Jan, 2022 @ 3:39am 
You could do that in celestial.config by adding a new PlanetaryType/SatelliteType with custom variationParameters (that contain possible planet sizes) and baseParameters that would include your planet as one of terrestrialTypes, but I'm not sure if just defining a new PlanetaryType would be enough to make it spawn in the game.
un'syelad 26 Jan, 2022 @ 7:14am 
uhm, is there a way to specify size or something like that?
Ceterai  [author] 22 Sep, 2021 @ 12:13pm 
@Rusty by default, all graphical assets and scripts of Starbound are packed into a packed.pak file in Starbound/assets folder. Check out one of these guides to know how to unpack it:
https://starbounder.org/Help:Unpacking_Game_Files
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=1161535874
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=732862019
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=2145917164
Retsu 12 Sep, 2021 @ 12:51am 
Interesting guide but i'm confused. I feel like I might have misread and I need clarification. I don't understand where all of these graphical assets are coming from and where to find them.
n3uva 10 Sep, 2021 @ 11:50am 
ok, if I changed it to fuel, which folder would it be located in?
n3uva 10 Sep, 2021 @ 11:32am 
thx thats all I need to know hopefully