Compiling A Primary Tileset
Note: this tutorial assumes that the porytiles executable exists on your system path. It also assumes your pokeemerald project is stored at the $HOME location. If your executable or project lives elsewhere, you'll need to change those paths in the commands below.
- Table Of Contents
- Setting Up The Layer PNGs
- Adding Tile Art To The Layer PNGs
- Creating The Tileset In Porymap
- Setting Up The Attributes
- Compiling The Tileset
- Mapping
- Making A Correction
- Next Steps
Let's get started! We're going to create a brand new tileset from scratch, so you can see how the process works from the ground up. The first thing you'll need is an image editor. I recommend either Aseprite or GraphicsGale, but you can use whatever you prefer.
Ok, let's go ahead and create a new folder to hold this tileset - I will create it in my home directory:
$ mkdir $HOME/porytiles-primary-tutorial
Porytiles compiles each layer of your tileset separately, so you'll need a separate RGBA PNG to represent each layer. Use your image editor to create three blank PNGs - you should name them bottom.png, middle.png, and top.png and save them to your tileset directory (for me that's $HOME/porytiles-primary-tutorial, for you that may be elsewhere). In order for Porytiles to work properly, the layer PNGs must be exactly 128 pixels wide, and their height must be a multiple of 16 (since a metatile is 16 pixels tall). For this tutorial, we'll make it 128 pixels tall, so it will be 8 metatiles tall. I also recommend filling your new PNGs with RGB=255,0,255, as this is the default Porytiles transparency color.
Your three layer PNGs should now look like the image below:
Now for the fun part! Let's add content to our layers. You can do whatever you want here. For the sake of example, I'll be pulling some tiles from TheDeadHeroAlistair's Project Heliodor Tileset, which is a wonderful tileset made available to the public with proper credits.
There is one major caveat. Many folks download DS tiles, or tiles designed for Pokémon Essentials, and then wonder why Porytiles is struggling. These tiles are not designed to work well within the GBA's color and palette constraints. Please only use tiles specifically designed for GBA, unless you really know what you are doing. Most tile artists will advertise their tiles as GBA-compatible.
With that caveat out of the way, here's what I came up with for bottom.png, middle.png, and top.png. Notice how I have separated out some of the artwork into different layers. This is so Porytiles can automatically assign your artwork to the correct metatile layer, which ensures that your tiles will look correct in-game. If you want to use these examples to follow along, you can find them here.
Before we compile our tileset, we've got a couple more things to handle. First, let's create a tileset and map in Porymap to use for testing. Go ahead and open your pokeemerald project in Porymap. In Porymap's menu bar, select Tools -> New Tileset. Create a primary set called PorytilesPrimaryTutorial. In Porymap's leftside panel, right click one of the map groups and create a new map called PorytilesTutorialMap. For this map's primary tileset, select gTileset_PorytilesPrimaryTutorial. Then save the map. Your Porymap window should look something like this, since the tileset is still empty:
Ok, now you've got a place for your compiled tileset to land. Finally, let's take care of the attributes. By default, Porytiles manages the metatile_attributes.bin file for you. Each time you compile your tileset, Porytiles will emit a metatile_attributes.bin file based on the content of attributes.csv and your tile layer information (if you are compiling with -dual-layer). This means that any attribute changes you made within Porymap will be erased each time you re-compile. If you really want to manage attributes via Porymap instead Porytiles, you should either compile with the -disable-attribute-generation flag, or set Porytiles to place its output in a temp location and then manually copy over only the files you care about.
Let's set up your attributes.csv file:
$ touch $HOME/porytiles-primary-tutorial/attributes.csv
Open the file in your editor of choice, paste in this content, and save:
id,behavior
6,MB_TALL_GRASS
This will set metatile ID 6 to have the tall grass behavior. You'll notice that metatile 6 on the layer sheets is the tall grass metatile. Awesome! Since we didn't specify any other tile, those will all receive a default value (which in this case is MB_NORMAL, but this is toggleable via the -default-behavior option).
For more information on metatile attributes, check out this wiki page.
Ok! We're finally ready to compile our tileset. Run the following command:
$ porytiles compile-primary -dual-layer -Wall -o $HOME/pokeemerald/data/tilesets/primary/porytiles_primary_tutorial $HOME/porytiles-primary-tutorial $HOME/pokeemerald/include/constants/metatile_behaviors.h
# Note that if your project is using triple layer tiles, simply omit the `-dual-layer` flag.
Now go back to Porymap and select File -> Reload Project from the toolbar. You should see your tiles show up in the metatile picker on the right! And you should see that the tall grass tile has the correct behavior attribute. Your Porymap windows should look something like:
Now you can start mapping! Here is what I did. Go ahead and create something like this and then save the map:
Ok, suppose we aren't totally happy with these tiles. We don't love the house's door color, so we're going to change it. Go ahead and open middle.png, and change the door. I am changing it to a greenish color:
Once you have done that, save, re-run the compilation command above, and then File -> Reload Project in Porymap. You should see something like this:
Awesome. Now you can see how easy it is to iterate on your tilesets using Porytiles! If you are curious about how Porytiles is assigning your palettes, you can easily see the palettes via Porymap's tileset editor. In Porymap's toolbar, select Tools -> Tileset Editor and then Tools -> Palette Editor. Here you can see how Porytiles decided to assign your palettes.
Finally, you may also have noticed that a file called assign.cache appeared in your $HOME/porytiles-primary-tutorial folder. We'll learn more about this file later, but essentially it's a cache file that stores the settings for the palette assignment algorithm. It helps subsequent compilations of the tileset possibly run faster. If you are keeping your tile assets in a git repo, I'd recommend adding assign.cache to the .gitignore list, as its contents frequently change and should not concern you or your collaborators (except in very particular circumstances).
Next, I suggest you read this tutorial's direct sequel, Compiling A Secondary Tileset. It will pick up right where this tutorial leaves off.