Palette Files

Palettes are PNG images. There is no JSON involved. What a palette PNG means depends entirely on where it sits.

Two locations, two meanings

Palette guides, for entities your pack owns:

Entities/<Entity Name>/Palettes/palette 0.png
Entities/<Entity Name>/Palettes/palette 1.png

Final palettes, contributed to entities another pack owns:

Palettes/<Target Pack>/<Entity Name>/palette 0.png
Palettes/<Target Pack>/<Entity Name>/palette 1.png

These are not interchangeable, and the difference is the single most important thing on this page.

Guides, for your own entities

Your entity's sprites are ordinary full-colour PNGs. The game cannot recolour them until it knows which colours are the palette.

Guides tell it. On load, the pack builds a default palette from the guides, converts every one of the entity's own sprite frames into an indexed-colour form against that palette, and then treats each guide as one selectable colour set.

Guide palette 0.png is the default: the colours as the sprites were drawn. Each further guide is the same colour slots in the same order, recoloured.

At least two guides are required for indexing to happen at all. With fewer, the converter does nothing and the entity keeps its literal sprite colours with no palette switching.

Final palettes, for other packs' entities

An entity from another pack — a Classic character, say — is already indexed. Your pack does not need to teach the game anything about its colours; it just supplies extra colour sets.

Files under Palettes/<Target Pack>/<Entity Name>/ are loaded directly as palette textures and appended to that entity's palette list. This is how you add new colour choices for Classic Axel without touching Classic's own files:

Editor/My Reskin/Palettes/Classic/Axel/palette 0.png
Editor/My Reskin/Palettes/Classic/Axel/palette 1.png

A folder under Palettes/ whose name matches your own pack is skipped: own-pack palettes belong with the entity, under Entities/<name>/Palettes/.

File naming and order

Files are named palette <n>.png and sorted numerically by the trailing digits, not alphabetically. palette 2.png comes before palette 10.png.

This matters because the position in that sorted order is the palette index — the number a level loadcue's paletteIndex or a character select choice refers to. Plain alphabetical sorting would reorder every palette from 10 onwards.

A file whose base name does not end in digits sorts last.

Authoring rules

Whichever kind you are making:

  • Keep the same dimensions across every palette for one entity.
  • Keep the colour order identical. Slot k in palette 3.png recolours whatever slot k in palette 0.png was.
  • Preserve transparent or reserved colours in the slots where the reference palette has them.
  • Palette 0 is the default and should be the entity's natural colours.

The safest way to make a new palette is to copy palette 0.png and recolour it in place, never adding, removing, or reordering pixels.

If a palette PNG fails to load as an image, the loader logs a warning and continues; the entity ends up with a placeholder in that slot rather than a hard failure. A silently wrong-looking character is usually a corrupt or wrongly-sized palette file.

How palettes get used

  • Character select cycles through the palettes available for the chosen character. In multiplayer, the select screen tries to skip palettes already taken so two players on the same character stay distinguishable.
  • Level loadcues pick a palette per spawn with palettePackName and paletteIndex, which is how the same enemy appears in different colours through a stage.
  • Scenes can apply an alternativePalette by name to the enemies in that scene.
  • HUD icons use the selected palette, via spriteSettings.json iconIndex.

An entity that borrows another entity's art through spriteSettings.json also borrows that entity's palette identity: palettes resolve against the reference entity, not the borrower.