Decompiling 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.

Defining Decompilation

Before diving into the tutorial, let's formally define some terminology you may have seen floating around.

Porymap-Format Tileset

Sometimes known as a compiled tileset, a Porymap-format tileset is a tileset in the input format expected by Porymap. That is, it's a tileset made up of an indexed tiles.png, a metatiles.bin, a metatile_attributes.bin, a palettes folder with numbered .pal files, and an optional anim folder containing named folders with animation assets.

Porytiles-Format Tileset

Sometimes known as a decompiled tileset, a Porytiles-format tileset is a tileset in the input format expected by Porytiles. That is, it's a tileset made up of three RGB (or indexed) layer PNGs (bottom.png, middle.png, top.png), an attributes.csv, an optional anim folder containing named folders with animation assets, and an optional palette-primers folder containing primer .pal files.

Compilation

Within the Porytiles ecosystem, compilation refers to the process by which a Porytiles-format tileset is transformed into an equivalent Porymap-format tileset.

Decompilation

Within the Porytiles ecosystem, decompilation refers to the process by which a Porymap-format tileset is transformed into an equivalent Porytiles-format tileset.

Choosing Our Tileset

For the purposes of this tutorial, we will be decompiling the tileset we compiled in the Compiling A Primary Tileset tutorial. If you want to follow along exactly, please go back and complete the tutorial so that you have a compiled version of the tileset featured there. You may also simply use any of the compiled primary tilesets from the vanilla game, though some special caveats about the vanilla tilesets are covered in Editing Vanilla Tilesets.

Decompilation Command

Decompilation is simple. We'll use the following command to decompile our tileset. Each argument and option will be explained below:

porytiles decompile-primary -o decompiled-primary-tileset $HOME/pokeemerald/data/tilesets/primary/porytiles_primary_tutorial $HOME/pokeemerald/include/constants/metatile_behaviors.h

-o decompiled-primary-tileset: like compilation, the -o option controls the output location. In this case, we'll write our output to a new directory called decompiled-primary-tileset in the current working directory. If it doesn't exist, Porytiles will create it. If there is already content there, Porytiles will overwrite it without prompting.

$HOME/pokeemerald/data/tilesets/primary/porytiles_primary_tutorial: this is the Porymap-format tileset we want to decompile. Here, we assume you are using the Porymap-format version of the tileset from the Compiling A Primary Tileset tutorial. If you'll be using a different tileset, replace this path with the path to your tileset.

$HOME/pokeemerald/include/constants/metatile_behaviors.h: like compilation, you need to supply a behaviors header (so Porytiles will know about the text labels that correspond to the behavior integral values). Replace this path with the actual path to your pokeemerald (or pokefirered/pokeruby) project's behaviors header.

And that's it! Check the output directory to see your Porytiles-format tileset, i.e. your decompiled layer PNGs and attributes CSV. You can now easily edit these and recompile them with compile-primary!

Transparency Normalization

By default, the Porytiles decompiler performs transparency normalization. For any transparent color in the input compiled tileset (i.e. the color in slot 0 of each palette), in the output decompiled layer PNGs that color will be changed to default Porytiles magenta: 255,0,255. This makes it really easy to recompile the tileset with Porytiles's default transparency configuration, and it does not affect the semantics of the tileset in any way. If you want to disable this behavior, supply the option -preserve-transparency. Alternatively, you can force Porytiles to normalize transparency to a different RGB color via -normalize-transparency=R,G,B. We will cover this topic a bit more in Editing Vanilla Tilesets, since this feature is essential when decompiling the vanilla tilesets.

A Note On Animations

At this time, Porytiles does not support automatic animation decompilation. The work for this feature is tracked in Issue #27. Until this feature is supported, you'll need to do some extra work to decompile animations yourself. With a competent image editor, this shouldn't be too hard. Vanilla compiled animation frames are already correctly indexed with an internal PNG palette, so the colors are correct. You can follow the following rough outline. For this example we'll assume you're converting the water anim to Porytiles format.

In your source Porytiles folder containing the freshly decompiled assets, create an anim directory.
Within anim, create a directory with the name of your anim, e.g. water
From the original compiled tileset, copy over all the water frame PNGs into the anim/water folder you just created, e.g. 0.png, 1.png, etc. Note: vanilla emerald anim frame PNGs have an internal palette, so Porytiles can read them like a regular RGB PNG without issue
Within your Porytiles source anim/water folder, create a copy of 0.png and rename it to key.png
Once you've done that, compile the tileset. You will probably get a ton of -Wkey-frame-missing-color and -Wcolor-precision-loss warnings.
Solve all of the above warnings. It will help prevent future bugs or issues, especially the pesky Issue #60.
Now you'll need to replace the vanilla placeholder water tiles on bottom.png, middle.png, and top.png with the correct subtile from your key.png.
Put in the driver C code and debug any issues that arise. See this section of the Adding Animations wiki page for help setting up the driver C code if you are unsure how that works.