Modding Discussion Modding Help/Request on Custom Ships

Discussion in 'Starbound Modding' started by Trapezoid, Nov 26, 2016.

  1. Trapezoid

    Trapezoid Orbital Explorer

    I'm interested in creating a custom ship to use in game, but I'm not entirely sure how to go about it at all. I'm decent enough with pixel art that I could probably pull out something worth looking at, but I'm not very well versed in modifying and the likes.
    I would very much like to create the Discovery One ship from the movie 2001: A Space Odyssey. Could anyone help me through the steps of creating a custom ship if possible? Many thanks!
  2. Antyrus

    Antyrus Pangalactic Porcupine

    The first thing you'll probably want to do, if you haven't already, is unpack the base assets. There's a tutorial around here somewhere. From there, you can take a look at the vanilla ship files in /unpackedassets/ships .
    You'll also want an advanced text editor like notepad++ if you don't have one already.

    Now, each ship technically has 9 tiers, numbered 0 through 8. Each tier, with the exception of 0, has four separate files. For example, apex tier 1 has:
    apexT1.png - This has your base pixel art. The block to pixel ratio is 1:8.
    apexT1lit.png - This is the same file as apexT1.png, but some parts are slightly transparent for lighting effects.
    apexT1blocks.png - This determines where blocks and objects are placed, and also determines where the ship boundries are. The block to pixel ratio is 1:1.
    apexT1.structure - This determines some of the actual ship data, like how many crewmembers you get, or whether your ship can warp between systems. It also determines the positioning of apexT1.png and apexT1lit.png(they probably won't line up with apexT[tier]blocks.png at later tiers, so you're gonna have to change this)
    You'll note that tier 0 only has two files. This is because it uses the ship images for tier 1, which is specified in apexT1.structure.

    Finally, outside of the files used for each individual tier, there's a blockKey.config. This file specifies what each pixel color is when the game looks at apexT1.blocks to place the blocks and objects.

    When you're making the ship pixel art, you'll want to use a grid tool if your image editor has one. This helps you keep your ship properly aligned.
    When you have your ship the way you want it, make a new empty layer and fill in every area you can walk with the color of the block you want to be there, as defined in blockKey.config. When you're finished, you can just scale it down to a 1:1 image and save it as your blocks.png.

    If all you want is one specific ship model, it's totally possible to make that one ship specifically and use it for every tier, as opposed to scaling up the ship every tier.
  3. bk3k

    bk3k Oxygen Tank

    Well another important thing would be universe_server.config pointing to your structure files. You'll want to read up on general modding guides, including how to patch that file.

    Besides checking out the base assets, check out a few mod ships.

    Now the blockImage seems like colors in a pattern, but not quite a ship.
    What those colors represent is defined in the blockKey. You'll see lots of entries like this
          "value" : [255, 255, 0, 255],
          "foregroundBlock" : false,
          "backgroundBlock" : true,
          "backgroundMat" : "apexshipdetails",
          "objectResidual" : true,
          "object" : "apexshiplight"
    for value, those numbers represent colors(as found in the blockImage). Red, Green, Blue, Alpha(opacity). Defining the alpha is optional - it will assume 255(no transparency). So placing a color defined by those numbers will place "apexshipdetails" tiles in the background, nothing in the foreground, and an "apexshiplight" too. The "objectResidual" will make the object stay between upgrades(otherwise it disappears, but a new one could be spawned and the player may not notice). "foregroundResidual" and "backgroundResidual" work in a similar manor, except for tiles.

    Anyhow you can add as many new entries as you want as long as they're all unique(and I have a huge blockKey). Note that 255, 255, 0, 255 is distinct from 254, 255, 0, 255 even if your eye can't tell the difference. But using contrasting colors is obviously to your benefit so you can see what's going on.

    Also you don't have to be THAT worried about the image lining up, because in your structure files you can do this
    "backgroundOverlays" : [
          "image" : "/ships/glitch/glitchT8.png",
          "position" : [498.625, 697.625],
          "fullbright" : true
          "image" : "/ships/glitch/glitchT8lit.png",
          "position" : [498.625, 697.625]
      "foregroundOverlays" : [
    As mentioned, your pixels are 8 to a tile. So that's 1/8th. If you where off by
    1 pixel, that 0.125,
    2 pixels would be 0.25,
    3 pixels, 0.375
    4 pixels, 0.5
    5 pixels, 0.625
    6 pixels, 0.75
    7 pixels, 0.875
    8 pixels, 1.00

    But note that your image's 'y' is reversed in Starbound versus your image editor(or at least it was in my case using

    And yes, if you put an image in foregroundOverlays instead, it will draw in front of the player. I thought about doing that for my dome, but it gets in the way of the plants.

    Oh also note you are limited to a 4096 x 4096 tile shipworld. Well that isn't an issue for most, but you might as well know.
    Last edited: Sep 23, 2017
  4. kittentamer

    kittentamer Existential Complex

    I'm looking into making a custom ship and this one post actually answered most of my questions!

    Though this gives me a new one:
    If I'm making a replacement for my base game race, can I just use the same filename as the config file will look for? It has been awhile since I started a mod from scratch, but a lot of the ship replacements I've seen you just swap the folder name and voila you're an avian on a human ship, with no patch file or anything. I hope I'm making sense. lol.

    (edit) and then I find my answer as I continue researching before I get started. Basically, it is better to make a patch and use unique filenames so it is more compatible with other mods. I suppose most people assume you won't mess with multiple ship mods at once so don't bother with that step. I'm also really tired at this point so I know there is more to it then that but that is what my brain comes up with atm. :p
    Last edited: Jan 5, 2017
  5. kittentamer

    kittentamer Existential Complex

    Further reading and thinking, when you mention the positioning, what do I base the positioning number on? I haven't started my mod yet, so it might become apparent later, but this has my gears turning atm. :p
  6. Antyrus

    Antyrus Pangalactic Porcupine

    I'm not entirely sure, tbh. Probably 0,0 is the bottom left corner of your image(because the coordinates are positive values representing blocks(8 pixels)), but I never actually tested. Personally, I just shifted it around until it fit. I will say this, though: If all of your ship tier images have the same dimensions and overlap correctly, you'll only have to figure out the position for one. You can then use that for all the others.
    kittentamer likes this.
  7. kittentamer

    kittentamer Existential Complex

    Alrighty then! I actually had one idea for a ship that would have it progressively getting fixed so you have access to more areas, in theory the images would have the same dimensions...A trial and erroring I go!
  8. bk3k

    bk3k Oxygen Tank

    Yes you can alternatively just replace a vanilla path/file as one way to do it. That wouldn't require a universe_server.config.patch file. But if you wanted say the Avian on a Human ship, the patch file would make for a smaller mod(no need to re-include the vanilla assets.) Alternatively you could edit the .structure files to point to another race's assets, but universe_server.config.patch is probably the most efficient way just like this.
          "op" : "replace",
          "path" : "/speciesShips/avian",
          "value" : [
    The images do start at [0,0] for the bottom left corner. That doesn't correspond to the actual in game(debug enabled) coordinates though. And you see where that's important when expanding your ship. Compare the lower tier ships with higher tier. Because the block image became larger, the offset changes to keep everything from shifting position.

    I'd recommend using the teleporter as your point of reference on that. Compare the position of the teleporter with the [0,0] offset to when the image expands. But... if you had identically sized blockImage files for all tiers, everything becomes easier(can just keep the offset [0,0]). You can have lots of empty/unused space and it isn't a problem. You're just deciding how much of your 2048 x 2048 shipworld is occupied by actual blocks is all. Including the red(255, 0, 0, 255) blocks -which just become indestructible invisible barriers (what are in practice probably metamaterial blocks).

    One other thing, run your PNG files through PNGGauntlet so that everything loads faster(because it will be smaller yet pixel perfect). Yes your blockImage files too.
    kittentamer likes this.
  9. kittentamer

    kittentamer Existential Complex

    Sweet. I have this thread bookmarked for reference as I go. :D
  10. bk3k

    bk3k Oxygen Tank

    What sort of ship are you building anyways? Any teasers?

    You might be able to save yourself lots of JSON building if you steal strategically re-purpose my blockKey from the Shipyard Rebuilt mod. It may already have color mappings for most everything you'll want. Where as vanilla blockKeys tragically share color mappings for different racial variants(for example every race's doors share a color), I do not - so you can use multiple race's stuff at once.

    You'd obviously still need to add mappings for any custom blocks and objects you have. But that may be a lot less work on your end compared to vanilla blockKeys.
  11. kittentamer

    kittentamer Existential Complex

    I was thinking of just experimenting and seeing what comes out, but I had planned awhile ago to update a Red Dwarf ship mod but at the time was daunted by how difficult it seemed, so I might actually work on that so I don't have to worry about trying to design something completely from scratch. lol. And part of the research would involve rewatching Red Dwarf, so no downside! :D
  12. Gunterman5

    Gunterman5 Void-Bound Voyager

    So i'm trying to make a block image for my ship and I'm kinda lost. I understand the color code but I'm having trouble understanding the positioning and dimensions of the colors. How can I tell if I've put too much or too little of the color and in what units do I scale the image down to 1:1 in?
  13. slowcold

    slowcold Pangalactic Porcupine

    One block = one pixel.

    For placing ship gear, you only need one pixel of that colour, in the place you want the item.

    Example from the apex block key:

    "value" : [255, 102, 0, 255],
    "foregroundBlock" : false,
    "backgroundBlock" : true,
    "backgroundMat" : "apexshipwall",
    "object" : "apexshipdoor"

    means on your blocks diagram, you would place a single pixel of colour 255, 102, 0, 255 in the position where you want the item - in this case a ship door.

    If the thing you are placing is bigger than a single block (like the ship locker, for example), the pixel you have put in is the bottom left hand corner of the item, so your item is placed up and to the right of that pixel. You still only need a single pixel of the defined colour though.

Share This Page