Palette Primers
Sometimes the Porytiles palette assignment algorithm just doesn't cut it. This is a common cause of the dreaded palette assignment parameter search matrix failed to find any suitable parameters error message. Luckily, Porytiles palette primers provide a way for you to "hint" the assigment algorithm with some sensible allocations. It's a way to "inject" human intelligence into the not-very-intelligent assignment process. If you find that Porytiles is struggling to assign your palettes at the desired palette count, or you notice Porytiles is duplicating lots of colors unnecessarily, it might be worth helping it out by providing some palette primers.
First step: create a palette-primers directory in your source folder, right along side your layer PNGs and attributes CSV. Within the palette-primers directory, you can place an arbitrary number of JASC .pal files. These .pal files may have arbitrary names, and can have a maximum of 15 colors, They must not contain the transparency color. Porytiles handles transparency automatically. Also, you'll also get an error if your actual pal size does not match the declared size.
Note
Porytiles accepts JASC .pal files with either CRLF or LF line-ending format. No need to worry about platform-specific line endings.
Given a set of properly formatted .pal files in your palette-primers folder, Porytiles makes the following guarantees:
- All colors in a given .pal primer are guaranteed to appear together in the same palette in the final allocation.
- Each palette primer becomes a special kind of tile. The palette primer tiles are pre-allocated, that is, Porytiles palette allocation runs on them before running on your tileset's regular tiles. Hence the "priming" terminology. Thus, tiles whose colors are covered by a palette primer are guaranteed to find a palette allocation without needing to "branch" the search algorithm, since their colors are already trivially present in the result palettes.
- Colors which appear in your layer sheets but are not present in the .pal primers will be allocated in the usual fashion.
- If the above conditions cannot be guaranteed, compilation will fail with an error message.
Please note: palette primers make no guarantees about the ordering of colors within a given palette, nor the final ordering of the output palettes. If you need these guarantees, see the wiki page for the palette overrides feature.
In the Resources directory, you can find a small example that demonstrates how palette primers alter the tileset compilation process. The example is a bit contrived, but it should serve to illustrate how the feature works.
Let's walk through compilation and see what happens. The bottom.png file is the only relevant layer PNG for this tutorial. It looks like this:
As you can see, one of the metatiles uses the door's red and the grass's green in the same subtile. I have deliberately setup this example so that it slightly stymies Porytiles's palette allocation algorithm. If you want to understand more deeply, check out the How Porytiles Works article. If you (understandably) don't want to read all this, the key takeaway is that this particular tile configuration will cause Porytiles to duplicate one of the door reds across two different palettes. Suffice it to say, a human can see this duplicate is not actually necessary.
So we'll start by compiling the without example, which does not make use of palette primers:
porytiles compile-primary -Wall -pals-primary-override=2 -tiles-output-pal=true-color -o without-compiled ./Resources/Examples/palette-primers-tutorial/without ./Resources/Examples/metatile_behaviors.h
Note the -pals-primary-override=2 and -tiles-output-pal=true-color, they are essential for understanding this tutorial. If you inspect the resulting tiles.png, you'll see this:
Notice that one of the door reds is duplicated. A human can look at this palette allocation and realize that it would be better if Porytiles had put all the colors in one palette, since there are less than 15 unique colors. Palette primers to the rescue! Let's create a .pal primer called colors.pal, which the following contents:
JASC-PAL
0100
13
64 72 104
96 96 120
200 64 80
216 104 96
255 0 255
64 176 128
112 192 160
96 168 232
112 184 240
128 128 136
160 208 192
184 200 224
248 248 248
Now, let's compile the with version of the tileset:
porytiles compile-primary -Wall -pals-primary-override=2 -tiles-output-pal=true-color -o with-compiled ./Resources/Examples/palette-primers-tutorial/with ./Resources/Examples/metatile_behaviors.h
Inspecting the tiles.png, you'll see:
Notice how now, Porytiles has placed all colors in the same palette. The red duplication is gone!
While this was a trivial example, you can extend the principles you've learned here to help Porytiles allocate more complex tilesets. Any time you see Porytiles duplicating colors that you know are not necessary, you can use palette primers to help it make better allocation decisions.