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. Compiled animation frames are already correctly indexed, so you'll simply need to determine which compiled palette the animation uses. And then you can create RGB animation frames that follow the format outlined in Adding Animations tutorial.

To wiki home page.

To project home page.