Modding:Tiled/Custom Tilesets

From Starbounder - Starbound Wiki
Jump to: navigation, search
Modding Documentation

Custom Tilesets (Advanced Usage)

The tilesets that come with Starbound are automatically generated from the assets using a tool that is not ready for use with mods yet. But if you’ve created your own materials and objects for your mod, there’s nothing to stop you manually creating tilesets for them.

Tilesets consist of the tileset .json file, and a collection of .png images, one for each tile in the tileset.

Both Starbound and Tiled have to be able to access the tileset .json file, so that must be located inside your mod directory and distributed within the .pak file. The recommended location is


The mod’s name is in the tileset path twice so that different mods can use the same tileset name as long as the mods have different names.

Only Tiled requires access to the image files though, so the recommended location for those is


To create a new tileset go to Map > New Tileset… and enter a name for your tileset. Choose “Collection of images” for the type of tileset. Your tileset will start off as an imported tileset. If you remember from earlier, I said that Starbound cannot read a map with an imported tileset, so you’ll need to export the tileset (Tiled-Export.png), and save it to a separate file in your mod’s directory.

Unfortunately, you can only edit a tileset that is imported, so each time you want to add a tile to your tileset you’ll have to import it (Tiled-Import.png), and remember to export it (Tiled-Export.png) again after your changes.

To add a tile, click the Add Tiles (Tiled-Add.png) button, then select the image for your tile from Starbound/tiled/modname/. Then you’ll need to set some properties on your tile to make it do things. Take a look at the properties on the tiles in the vanilla tilesets to see how that works. Some important properties are “object”, “material”, and “liquid”. You could, if you wanted, also create tilesets for monsters and NPCs, since the same properties we used on the rectangle tool also work here.

Removing tiles is dangerous if other maps use the tileset because it changes the tile indices those other maps are using. Instead of removing tiles, we instead recommend leaving the tile in the tileset and just removing the properties.

When distributing your mod, make sure your tileset’s .json file is packed along with the rest of your mod. If you want other mod developers to be able to use your tilesets in their own Tiled maps, you’ll need want to distribute the images in Starbound/tiled/modname-custom/.