Palette Overrides

Motivation

You may have noticed that palette primers do not give you control over the ordering of the output palettes, nor the ordering of colors within each palette. For direct control over palette and color orderings, palette overrides are the right choice. This feature may be especially useful for:

DNS systems which expect window lights to be in specific, fixed palette slots
Forcing tile sharing, i.e. saving tile space by storing one tile that can index into multiple palettes, e.g. the vanilla Pokémart and Pokécenter roof tile
Cases where you want to manually construct palettes, or re-use palettes you already created manually
Fixing the palette slots for your door anim colors, so they don't keep breaking as you update your tileset

Palette overrides and palette primers are complementary features. Both will work together, and (in most cases) play nicely with Porytiles's automatic palette assigment algorithm.

How To Use The Feature

First step: create a palette-overrides directory in your source folder, right along side your layer PNGs and attributes CSV. Within the palette-overrides directory, you can place a JASC .pal file for each output palette you want to override. E.g. if you want to override some slots in output palette one, then place a JASC .pal file called 01.pal in your palette-overrides directory.

A palette override JASC .pal file is like any other JASC .pal file, except it allows for a special wildcard - symbol which denotes any color. You can use this symbol to tell Porytiles that you don't care what it puts at this particular slot. That slot is "open" for Porytiles's automatic palette assignment algorithm to freely use.

A palette override JASC .pal file must have a declared size of 16, and must use the wildcard - symbol in the 0th pal slot. This is because pal slot 0 is always transparent. So we need to leave that slot open so Porytiles can place the transparent color there. You'll get an error if either your declared pal size isn't 16 or if your 0th pal slot isn't set to -. 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.

Here's a simple example. Suppose you want output pal 1 in your primary tileset to contain a particular red tone in pal slot 2, and a particular green tone in pal slot 3. You don't care about the contents of any other palette slots. Create a 01.pal file with the following contents, and place it in your palette-overrides folder:

JASC-PAL
0100
16
-
-
240 20 40
50 200 40
-
-
-
-
-
-
-
-
-
-
-
-

After compilation, you should see that your 01.pal in the output palettes directory contains the colors you specified at the appropriate slots!

Case Study: Tile Sharing

Let's now look at a more complex example which showcases how you can use palette overrides to pull off a tile sharing optimization.

Compiling Without Overrides

In the Resources directory, you can find a small primary set example that demonstrates how palette overrides 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 tileset bottom, middle, and top layers look like this:

First, we'll compile without the overrides. Note that we have explicitly overriden the primary palette count to 3. This is crucial for understanding the example.

porytiles compile-primary -Wall -tiles-output-pal=true-color -pals-primary-override=3 -o without-compiled ./Resources/Examples/palette-overrides-tutorial/primary-without ./Resources/Examples/metatile_behaviors.h

The result of this compilation:

As you can see, a lot of the building roof tiles are essentially duplicated with a red and blue version of each. The palettes are also quite scrambled and aren't grouping the colors logically. We can do a lot better. If we can make the corresponding reds and blues line up in two different palettes, then we can force Porytiles to generate one tile that correctly indexes into multiple palettes, saving quite a bit of tile space.

Tile Sharing: Mathematical Definition

So what exactly do we mean by "make the corresponding reds and blues line up in two different palettes?" Consider the pairs tiles marked by the matching arrows in the picture below:

If you look closely, you'll notice that each tile "pair" denoted by equivalent-colored arrows looks like the same tile, just with shifted colors. That is, for each tile pair [T1, T2], where both T1 and T2 contain N unique colors, each unique color U_n in T1 maps to one and only one corresponding color V_n in T2. And each unique V_n in T2 maps to one and only one corresponding color U_n in T1. In some cases, U_n and V_n are the same color. Other times, they're not. The point is, U_n and V_n always correspond in a given tile pair.

In other words, two tiles T1 and T2 are "sharable" when:

The set U of unique colors in T1 has cardinality N
The set V of unique colors in T2 has cardinality N
The pixel-mapping function f that yields the V_n in T2 for any U_n in T1 is an involution

To construct your palette overrides such that T1 and T2 share hardware tiles, you simply need to list all the colors of U in one palette and all the colors of V in another palette

TODO : revamp this whole explanation

Warning

If these conditions do not hold, then you don't have a candidate for tile sharing, and overrides won't help you here.

Setting Up Tile Sharing: In Practice

Usually, the easiest way to get started is to pick some pair of tiles T1 and T2, then figure out the full set U of unique colors in T1 and the full set V of unique colors in T2. Then, choose a palette to use for U and a different palette to use for V. Then line up the colors in each palette such that color U_n and color V_n are in the same palette slot. For this example, we've already constructed some palettes that satisfy all these constraints. See below:

00.pal

JASC-PAL
0100
16
-
248 184 128
200 64 80
232 144 112
216 104 96
96 96 120
64 72 104
216 224 232
248 248 248
128 128 136
152 176 216
184 200 224
-
-
-
-

01.pal

JASC-PAL
0100
16
-
112 184 240
72 112 168
96 160 216
80 136 192
96 96 120
64 72 104
216 224 232
248 248 248
128 128 136
152 176 216
184 200 224
-
-
-
-

We did a bit of work behind the scenes to put these pals together, but if you inspect them closely you'll see how they make sense. The first four colors in each are the corresponding reds and blues. You'll notice the rest of the colors are identical. These are the various greys that are shared between the mart and center tiles. Finally, let's create a 02.pal for the tree greens. You'll see why this is important later:

02.pal

JASC-PAL
0100
16
-
-
-
-
-
-
-
-
-
-
-
-
56 136 48
176 248 128
56 80 0
128 192 96

Take these three palettes and place them in your palette-overrides directory. Now compile again:

porytiles compile-primary -Wall -tiles-output-pal=true-color -pals-primary-override=3 -o with-compiled ./Resources/Examples/palette-overrides-tutorial/primary-with ./Resources/Examples/metatile_behaviors.h

The result of this compilation:

Notice how many fewer tiles we're using now! You can also see the palettes are "lined-up" in such a way that corresponding colors use the same slot. Great!

Tile Sharing Across Tileset Boundaries

TODO

Manual Palette Allocation With Overrides

Palette overrides provide a way to force Porytiles to use a manual palette allocation. For example, let's assume you want to manually allocate the palettes for a pokeemerald primary tileset. First, create your palette-overrides directory within the Porytiles-format tileset directory. Then, copy your 00.pal through 05.pal into the palette-overrides folder. Finally, open each palette and adjust the declared size to 15 and remove the transparency color in slot 0. If your tiles are not allocatable with the palettes you've provided, you'll receive the usual error message.

This functionality is very useful in the following scenarios:

You want Porytiles to handle tile flip/dupe optimization and metatile construction, but you'd like to set up palettes manually.
Porytiles is struggling to allocate palettes for your tileset, but you know it's possible and can see where the allocation algorithm is going wrong.
You have an old manually-constructed Porymap-format tileset that you've imported to Porytiles-format via the decompiler, but you want to keep your original, manually-constructed palettes.

To wiki home page.

To project home page.