How to mod your ship.

Discussion in 'Starbound Modding' started by WickedWitch, Dec 5, 2013.

Thread Status:
Not open for further replies.
  1. WickedWitch

    WickedWitch Big Damn Hero


    Having been away from the game for such a long time, my tutorial made not work as intended...or at all. The file structure has fundimentally changed since I wrote this and is in my opinion outdated. Hence why I don't support it any more.

    If I do get back into modding the game and work out how to successfully mod the ship again then this will be updated. Until then you may find a better tutorial elsewhere. Sorry for any inconvenience!


    This guide attempts to instruct you on how to design your own race ships, and replace your characters current ship.

    First things first, you will need a good .txt editor. I use Notepad++. It has been recommended by some Chuckfish devs too.​
    Modding your ship.

    Modding ships and adding them to game.

    This guide attempts to instruct you on how to design your own race ships, and replace your characters current ship.

    First things first, you will need a good .txt editor. I use Notepad++. It has been recommended by some Chuckfish devs too.

    You will also need a decent image editor, that can handle transparency and can export the images into .png format. I use GIMP, it's free, powerful and did I mention free?

    You may want to start off by simple editing an already existing ship, as it has the general dimensions and works as a decent base for starting your first ship design/redesign.

    All the ship files are found here:
    C:\Program Files (x86)\Steam\steamapps\common\Starbound\assets\ships
    (The location may vary, based on your Steam installed location)

    This is where all the different race's ships are located. Go ahead and pick your race and you should find the shipship.png

    We will start with the human ship for ease.

    The shipship.png file is the background of your ship. It doesn't have any physical manifestation beyond being the ship's background in-game.

    This can be designed any which way you desire with no real dire consequences. You could even just do a paint job on your ship and change it's colour. Or even add decals.

    All colour values in dropship.structure are in RGBA values (0,0,0,255) The "A" is alpha or transparency. 255 means no alpha (fully visible) where as 0 would be completely invisable.

    Transparency is carried over ingame, so where it exists in this .png it will be in-game, even half transparency. Which should be good for things like glass.
    [​IMG]The modded shipship.png background file
    Editing dropshipblocks.png

    You will also find other related files: dropshipblocks.png (This is the image that tells the game what blocks to place and where.)

    The file dropship.structure defines what the blocks are and what their corresponding colour is, for use in the dropshipblocks.png image.

    This with further effort could allow you to place different types of blocks on your ship outside of the default ones.

    All colour values in dropship.structure are in RGBA values (0,0,0,255) The "A" is alpha or transparency. 255 means no alpha where as 0 would be completely invisible.

    The dropshipblocks.png file.

    This file is at a 1:8 ratio to shipship.png
    Meaning 1 pixel in dropshipblocks.png = 8 pixels in shipship.png.
    (Thanks to various sources for that, you know who you are.)
    This is the lines that define what image file the ship uses.

    "backgroundOverlays" : [
          "image" : "shipship.png",
          "position" : [7, 11]
    "Image" : "SHIP.png", - The image file that is the background of your ship in-game
    "position" : [X,Y] - The starting position of the SHIP.png. Can be used to ship your ship's background about if it's not quite exact.

    There should be a few more of these lines, each one defines the colour in RGBA value and it's function. The first three are invisible blocks, which can allow you to control the physical confines of your ship.

    Invisible Control Colours:

    White (Free-for-all):

    "blockKey" : [
          "value" : [255, 255, 255, 255],
          "foregroundBlock" : false,
          "backgroundBlock" : false
    This pure white colour is empty space in-game wise, that doesn't have objects or any blocks, foreground or background. But still allows you to place objects and allows movement.

    Blue (No objects please):

          "value" : [0, 0, 255, 255],
          "foregroundBlock" : false,
          "backgroundBlock" : true
    This pure blue colour only allows background, and will not allow you to place objects within it's area.

    Red (Absolutly nothing):

          "value" : [255, 0, 0, 255],
          "foregroundBlock" : true,
          "backgroundBlock" : true
    This pure red colour is what prevents everything, even the player from moving. And will take up the most of the image. Essentially it is used to create the boundaries of your ship.

    Placing objects:

    Yellow (Let there be light(s)):

          "value" : [255, 255, 0, 255],
          "foregroundBlock" : false,
          "backgroundBlock" : true,
          "backgroundMat" : "apexshipdetails",
          "object" : "apexshiplight"
    As you can see, this yellow colour defines where the ship's lights go.

    "Object" : "OBJECTNAME" - Controls if there's an object at the placed pixel, remember that it's the bottom right of the object in-game.

    Adding both foreground and background:

    If you want to add both a foreground and a background block and don't want to have to place them manually add the following:
          "value" : [xxx, xxx, xxx, 255],
          "foregroundBlock" : true,
          "backgroundBlock" : true,
          "foregroundMat" : "MATERIAL",
          "backgroundMat" : "MATERIAL"

    Value - Want ever value you want as long as it's not already being used.
    Foregroundblock - Set this true.
    Backgroundblock - Set this true.
    ForegroundMat - the name of the material (Has to be a .material file, but don't include the file extension.
    BackgroundMat - same as foreground, but will be in the background. Can be different too.

    If you want your custom colour to make sure that the blocks you place are permanent, and can't be removed with any tool, place the following:

    "objectParameters" : {
    "unbreakable" : true

    Use the dropship.structure file to guide you to the already used colours in dropshipblocks.png. You should note the each object block is only 1 pixel, and is the bottom right placement for objects.

    This file can also be used to increase the maximum amount of fuel your ship can hold. change the value of:

    "fuelMax" : 1000

    to what ever you like.

    Make sure at the end of the colour definitions you end the coding with " ], " (without quotation marks)

    This is the file that correspond to all the colour deffinitions.

    "blockImage" : "dropshipblocks.png"

    Make sure the whole file is wrapped with both { }

    Adding files to the game:

    First things first, make sure that you make back ups of any and all files your change or alter. I won't be held responsible for damages to your game or computer. I have successfully altered my human ship to increase in size.
    Make sure the game is not running or this will not work!

    !Make sure to make back ups of all your files you intend to change. I won't be held responsible for any damages to the game or your computer!

    !!! These steps will change the contents of your ship, any and all items you have stored as both furniture, blocks and items in stored containers with all be lost. But this step is required. Simply take every thing out prior to changing your ship and store it planet-side. !!!


    Replacing ship files:

    1) Goto X:\Program Files (x86)\Steam\steamapps\common\Starbound\assets\ships\RACE (where "x" is the drive Starbound is installed.)

    2) Make backups or move into a seperate folder the following files: dropshipblocks.png and shipship.png

    3) Alter the files to your liking.
    (Check the file dropship.structure for each colour and it's function. Use an image of the ship and correlate them according to the colours found in the file dropshipblocks.png)

    4) Save the files.

    The following step is for already created characters!

    !!! The next step will change the contents of your ship, any and all items you have stored as both furniture, blocks and items in stored containers with all be lost. Simply take every thing out prior to changing your ship and store it planet-side. !!!

    It is not required for new characters!

    Replacing the block data:

    After editing the files: dropshipblocks.png and shipship.png follow these steps:

    1) Goto X:\Program Files (x86)\Steam\steamapps\common\Starbound\player (where "x" is the drive Starbound is installed.)

    2)Take note of your main character's ID. This will be the file xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.player (The "x" will be random numbers and letters)

    3) Load the game and create a new character. Based on the race of the ship you edited.

    4) Exit the game.

    5) Goto back to C:\Program Files (x86)\Steam\steamapps\common\Starbound\player

    6) Change the new character's yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy.shipworld with your characters ID.
    (eg. yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy.shipworld change to xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.shipworld.)

    7) Start the game and you should have you new ship.

    My Ship as it now stands in my Starbound game.

    For Modders:

    To help others download and make better use of your modded ships, package your new xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.shipworld (without the 32 character ID), along with your dropshipblocks.png shipship.png and dropship.structure files. So that it's placed into the ...\starbound\player folder.

    For players

    When you have downloaded and installed a ship mod with the already placed .shipworld file.
    Add in your player 32 character ID.
    Make sure to create a backup or rename your current player .shipworld incase something goes wrong.


    Replace the files you had changed with the ones you SHOULD have back upped. Assuming you followed instructions correctly.


    Any and all images and files used are property of Chucklefish, and are modded for non-commercial usage. You modify your game at your own risk, I won't be held responsible for any damage to your game or computer.


    I've uploaded my first guide to Steam, it's how to mod and add your ship to Starbound. It's a first draft, so forgive the mistakes.

    Any and all comments welcomed. As it's my first guide it's a little rough.
    Last edited: Jul 21, 2014
  2. Master Catfish

    Master Catfish Void-Bound Voyager

    I'm confused on why this hasn't gotten any responses yet. I think this guide should be stickied, assuming it works. I haven't tried it, and it might be too complicated for me, but it sure seems cool!
  3. InsanityCow

    InsanityCow Tentacle Wrangler

    Is it possible to increase the size of the ship? Like, say I want the Enterprise (or at least the bridge)
    metalG likes this.
  4. Btamb

    Btamb Master Chief

    You can do a lot to the ship, this is the first one that I made. I always felt like I never had enough room on my ship.
    WickedWitch and InsanityCow like this.
  5. InsanityCow

    InsanityCow Tentacle Wrangler

    Hopefully the team will have a system that provides results like this in the future (perhaps upgradeable parts or even changing ship type), otherwise much thanks for the tutorial :)
  6. kurtjp

    kurtjp Space Hobo

    I'm really thinking of designing some new ships, it looks like it could be some real good fun.
  7. thenightgaunt

    thenightgaunt Void-Bound Voyager

    Ok, I love this idea.
  8. Lynx88

    Lynx88 Phantasmal Quasar

    Thanks for the guide, its gonna be very helpful indeed for custom ships.

    One question, how do you line up the tiny "dropshipblocks" image with the full size ship accurately?
  9. CrazyChris

    CrazyChris Intergalactic Tourist

    Can i take a profile picture of an already existing ship and add the interior to it?
  10. dominichello

    dominichello Tentacle Wrangler

    the way i did it for my ship was to first do all the artwork, and block file. stick it in game and see where it overlapped. As long as you work on the 8:1 pixel ratio you can get it to align.
    You then need to modify the dropship.structure file and change the entry :

    "backgroundOverlays" : [
    "image" : "shipship.png",
    "position" : [9, 12]

    The position is the alignment of the artwork to the blockfile. Its a bit hit and miss, but change values to see what happens. Trial by error you will eventually work it out. You may have to nudge your artwork file a few pixels here and there, then resave it to get it to align perfectly. Once you do its well worth it :) ....

    Zailiner, Magma Claw and WickedWitch like this.
  11. Lynx88

    Lynx88 Phantasmal Quasar

    8:1 pixel ratio? That's... gonna be annoying to match, lol. Thanks for the info!

    The ship I want to make is actually very huge.... something around the scale of the space station in length. Gonna be really tough getting the coordinates right. :\
  12. Tamarama

    Tamarama Guest

    Since the blocks file is available to other players even on non-local servers, and the backdrop art (shipship.png) is not, it seems like the best thing to do is to create a big open space in the block file, surrounded by a small red line. Then you could use that space as a ship construction space, and build the ship you want in-game. That way the whole project would be completely visible to other players.

    For reference, I've added what a ship looks like when another player doesn't have the same mod. I used a premade ship from nexusmods:
    What it looks like to you:
    What it looks like to your friend without the mod:
    Last edited by a moderator: Dec 9, 2013
  13. dominichello

    dominichello Tentacle Wrangler

    ive seen the method, and in all honesty i think they look really bad :/ i dont think it suites the ships to be built out of blocks. Just personal preference, but i appricate it makes it compatible with all players and is much simpler.
  14. Magma Claw

    Magma Claw Existential Complex

    Can u pls pm me with a download link to that :p I would really appreciate it
  15. Tamarama

    Tamarama Guest

    A few random bits of info from testing:
    • There can be multiple ship lockers, and they are not linked (they hold different inventory).
    • There can be multiple transporters.
    • Lockers, 3D printers, and Fuel Tanks need have background tiles to link onto
    • Engines, Transporters, and Capt Chairs need either Redspace or Foreground Blocks to attach to. Below them mostly. Rear engines want them to the right.
    • Bottom thrusters need white or red space above them.
    • Setting everything to "unbreakable" : false from true makes it a lot easier to design in game. If you do this, make sure they have a backgroudMat set, otherwise you'll have a permanent hole in your bg.
    • "foregroundMat" is a valid property even though it doesn't appear in your .structure, so don't forget to set it if you're adding a foreground material
    • new entries into the .structure fine, other players will be able to see them as intended.
    Hope that saves someone some time.

    If anyone can figure out how to put in water for my my Hylotl, I'd be in your debt.
    Last edited by a moderator: Dec 10, 2013
    Sprunt and dominichello like this.
  16. tiltos

    tiltos Void-Bound Voyager

    This guide is great. The one issue I'm having trouble with the background of platform mats. Any ideas? I've tried setting backgroundMat, but no luck.

    P.S Will post my redesigned Apex ship soon!
  17. Spartan190

    Spartan190 Void-Bound Voyager

    Great guide thank you.
    Does this also work in multiplayer? So I edited my ship for my race, an other one uses this race, too, does he still have is original ship when I beam on his ship and he will be able to see my edited ship when he beams to mine?
  18. dominichello

    dominichello Tentacle Wrangler

    atm it breaks in multiplayer...both players will need the modified files, and a new character to get it to work (or modified ship files for an old character)

    BUDDYBOY Astral Cartographer

    Here's what I recently did.

    Apex Ship Img.jpg
  20. Tamarama

    Tamarama Guest

    Replying to my own post, but the best workaround for this seems to be creating a new gun with "lavaballoon" as the projectile, and spawning one in your chest. Lavaballoon makes water, go figure. Then you can fill anything, including your ship, with water,
    kitsunespirit likes this.
Thread Status:
Not open for further replies.

Share This Page