Starbound

Starbound

Not enough ratings
Modding: Species Ship Guide
By Ceterai
Creating a custom ship, ship pet, ship objects and ship upgrades for your species? I'll try to help you with this guide.
WEBSITE[ceterai.github.io] | SUPPORT ME[buymeacoffee.com]
   
Award
Favorite
Favorited
Unfavorite
Introduction
This guide cover the following parts of creating a ship for your species:
  • creating the ship objects
  • drawing the ship layouts
  • creating the ship pet
The guide covers BYOS ships from FU a little (removing the background part) in the end of the second section of this guide.
The guide assumes you know modding basics (unpacking assets, creating objects).
Ship Objects
These are any objects that are meant to be part of your ship by default, removable or not.
Usually, these include:
  • Teleporter
  • S.A.I.L. Console
  • Fuel Hatch
  • Navigation (Captain's Seat)
  • Locker
  • Locker T0
  • Light
  • Broken Teleporter
  • Broken S.A.I.L. Console
  • Broken Fuel Hatch
  • Vertical Hatch (removable)
  • Horisontal Hatch (removable, optional)
  • Secondary Locker (removable, optional)
They are all usually located under this path:
/objects/ship/
For example:
/objects/ship/apexcaptainschair/ /objects/ship/apexfuelhatch/ /objects/ship/brokenapexfuelhatch/ /objects/ship/apexshipdoor/ /objects/ship/apexshipdoorbroken/ /objects/ship/apexshiplight/ /objects/ship/apexshiplocker/ /objects/ship/apexshiplockerTier0/ /objects/ship/aviantechstation/ (S.A.I.L.) /objects/ship/aviantechstationTier0/ (Broken S.A.I.L.) /objects/ship/avianteleporter/ /objects/ship/avianteleporterTier0/
If you don't know how to create according objects, you can use these as base.
Ship Layout
Probably the most difficult part of the process is drawing 9 ship layouts, 9 ship backgrounds, 8 ship transparent layers with different levels of transparency, and editing 9 configs to go along with them, one for each tier of the ship.

You you don't want to go through this pain (at least for now), you can simply copy a vanilla ship, change the species name in the file names, and use it for your species.

Still, if you decided to do this, here we go.
Create The Structure
Ship configurations are usually located under this path:
/ships/<species>/
Here and below, <species should be the name of your species.
The files inside look like this:
/ships/<species>/ blockKey.config <species>T0.structure <species>T0blocks.png <species>T1.png <species>T1.structure <species>T1blocks.png <species>T1lit.png ... <species>T<tier>.png <species>T<tier>.structure <species>T<tier>blocks.png <species>T<tier>lit.png
Here, <tier> is a number from 0 to 8 inclusive (hence 9 tiers total).
Notice how T0 has less files than the rest. This is because it's using some files from T1.
What do we have here:
<species>T<tier>.png
Background image of the ship in current tier.
<species>T<tier>lit.png
Same as background image, but with different levels of opacity to account for light & shadows.
<species>T<tier>blocks.png
A block map of the ship that shows the game what blocks and objects should be placed in what space.
blockKey.config
A JSON color map config file. This is where you can configure what objects and blocks are placed in your ship by default by editing values undercorresponding colors used in <species>T<tier>blocks.png files.
<species>T<tier>.structure
A JSON configuration for a ship tier which uses all of the files above.
Edit The Structure
This step is simple but tedious:
  • change the filenames mentioned in all .structure files to your species ones.
  • update the blockKey.config file with your object IDs if needed.
  • edit the png files. This is the hardest one in my opinion. Good luck.
If you feel like you've got the hang of it, fell free to make other edits as well!
BYOS
If you're playing with FU and want to make your ship into a BYOS one, make sure that your <species>T0.structure file has the "backgroundOverlays" property as an empty list, like so:
"backgroundOverlays" : [ ]
Ship Pet
This part consists of 2 steps:
  • creating a ship pet
  • adding it to your S.A.I.L.
If you'd like to use an already existing pet (a vanilla one or from another mod), you can skip the first step.
Creating A Ship Pet
A ship pet is a "monster" just like all non-npc enemies (poptops, etc.), critters and bugs.
The difference is that its specific parameters make it:
  • persistent
  • ignore all damage
  • have a bit of different lua logic
  • use random sprite version out of a set of sprite versions
Most vanilla non-npc creatures in Starbound don't have these qualities.
Usually, ship pets are located under the following folder:
/monsters/pets/
For example:
/monsters/pets/snugget/ snugget.monstertype snugget.animation parts/ blue.monsterpart blue.png ... default.frames
What's happening here:
<pet "type">.monstertype
The main JSON file that defines your ship pet. Here, the parameters you'll need are:
  • "type" : "snugget", - the type name of your pet. Must be unique.
  • "categories" : ["snugget"], - category from your .monsterpart files (see below).
  • "parts" : ["body"], - parts from your .monsterpart files (see below).
  • "animation" : "snugget.animation", - relative path to your .animation file.
<pet "type">.animation
A JSON file containing animation config. This quide won't cover how to configure these as it's quite a lot to go through. Doesn't have to be named the same as the .monstertype file, but make sure to write a proper name in the .monstertype file in that case.
parts/
Subfolder containing sprite version definitions. It doesn't have to be in this folder, but it's convenient.
Note that in order to have multiple sprite versions to be randomly chosen, you need to have multiple .monsterpart files with the same "category" and "type".
parts/<color>.monsterpart
A JSON monster part file that defines what sprites should be used for a certain part of a monster. Since most monsters only consist of one part (the entire body being one part), you'll only need one to have a proper color version for your ship pet. An example of multiple body parts would be triplods - their heads and legs are separate and have separate .monsterpart files.
The file structure is as follows:
{ "name" : "<color>", "category" : "<part category, usually matches your pet "type">", "type" : "<part name that should match what's used by the animation file, usually just "body">", "frames" : { <part state as mentioned in the animation file> : <relative path to the sprite file> } }
Example:
{ "name" : "blue", "category" : "snugget", "type" : "body", "frames" : { "body" : "blue.png" } }
parts/<color>.png
A sprite file that corresponds with the monsterpart it's used by. Doesn't have to have the same name, but it's convenient.
default.frames
A JSON file defining frames for a sprite png. If called "default.frames", will be the default definition for all pngs in the current folder and its subfolders. You can specify frames for some of the pngs individually by giving the frame file the same name as the png file. For example, "blue.frames" will correspond to "blue.png" and will be preffered by the game over "default.frames" if there is one.
You can create your own pet based on this information.
Attaching The Pet To SAIL
Now lets make it so your pet actually spawns in your ship.
All you need to do to make this work is to set the "shipPetType" value in your S.A.I.L. .object file to your pet "type", like so:
"shipPetType" : "snugget",
Or, if you're creating a patch for someone else's mod, then you should create a ".object.patch" file and put this in it:
[ { "op" : "replace", "path" : "/shipPetType", "value" : "snugget" } ]
My Enternia example: Alta Ship Pet - Snugget Patch[github.com]
That's it!
Conclusion
This is all I have to share on this topic. Let me know if there's anything I'm missing! ^^
Helpful Resources
The guide mentions patching in the 3rd section. If you're not familiar w/ it, here's a helpful guide:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=2124444255
More about ship upgrades:
https://starbounder.org/Ship_Upgrade

Testing upgrades:
https://starbounder.org/Ship_Upgrade#Admin_upgrade

Creating objects:
https://starbounder.org/Modding:JSON/Variables/Objects