Palette Overrides
- Table Of Contents
- Motivation
- How To Use The Feature
- Case Study: Tile Sharing
- Manual Palette Allocation With Overrides
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.
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!
Let's now look at a more complex example which showcases how you can use palette overrides to pull off a tile sharing optimization.
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 contain quite a bit of color duplication. 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.
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.
Note
If this condition does not hold, then you don't have a candidate for tile sharing, and overrides won't help you there.
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.