Palette

Every pixel on PICO-8 is stored as a 4-bit value in memory. Because a 4-bit value can only hold the values 0-15, this means pixels can only choose from a list of 16 colors. This list is referred to as the palette.

PICO-8 has three layers of palettes. Only the first two are configurable. The first is used during each draw call, re-mapping the requested 4-bit indices to the 4-bit indices that are actually written to screen data memory. The second is used when the frame is presented to the viewer, re-mapping the 4-bit indices in the screen data to 8-bit system color indices. The third maps the 8-bit system color indices to pre-defined R,G,B values.

The draw palette (#0)

Each draw call uses the current draw palette to map the input 4-bit palette indices (either from parameters or sprite pixels) to the 4-bit values which are actually written to screen data memory. The written values will, in turn, be used by PICO-8 to index into the screen palette (see below) when the frame is ready to be presented to the viewer.

By default, draw palette indices 0-15 are mapped 1:1 to screen palette indices 0-15. This mapping can be changed by adjusting palette #0 with a call to pal(draw_palette_index, screen_palette_index).

The draw palette is useful for things like palette-swapped sprites, where you have one sprite image that can be drawn for, say, different teams or ranks with different uniform colors.

The draw palette also has a transparency flag per entry. If set, sprite pixels with that index will not be written. It can be changed with a call to palt(draw_palette_index, true/false). By default, index 0 is flagged as transparent, but it's possible to flag any index, or multiple indices, or none.

The draw palette can be changed at will, affecting subsequent draw calls. Unlike the screen palette, it does not need to be the same for the entire frame. However, it can only choose from the 16 colors that are in the screen palette. It cannot choose directly from the larger system palette.

The screen palette (#1)

The screen palette maps pixel indices found in screen data memory to indices in the larger system palette, which currently contains 32 pre-defined colors. See System palette below for details.

By default, screen palette indices 0-15 are mapped 1:1 to system palette indices 0-15. This mapping can be changed by adjusting palette #1 with a call to pal(screen_palette_index, system_palette_index, 1).

The screen palette may be changed any time during or between frames, but only the screen palette which is set at the time the frame is presented to the user will actually be used. It is not possible to split the screen into sections which configure the screen palette differently. No single frame may contain more than 16 colors.

The system palette

0..15: Official base colors

These are the 16 system colors the screen palette is mapped to when PICO-8 starts up:

Index	Hex	RGB	Name
0	`#000000`	`0, 0, 0`	black
1	`#1D2B53`	`29, 43, 83`	dark-blue
2	`#7E2553`	`126, 37, 83`	dark-purple
3	`#008751`	`0, 135, 81`	dark-green
4	`#AB5236`	`171, 82, 54`	brown
5	`#5F574F`	`95, 87, 79`	dark-grey
6	`#C2C3C7`	`194, 195, 199`	light-grey
7	`#FFF1E8`	`255, 241, 232`	white
8	`#FF004D`	`255, 0, 77`	red
9	`#FFA300`	`255, 163, 0`	orange
10	`#FFEC27`	`255, 236, 39`	yellow
11	`#00E436`	`0, 228, 54`	green
12	`#29ADFF`	`41, 173, 255`	blue
13	`#83769C`	`131, 118, 156`	lavender
14	`#FF77A8`	`255, 119, 168`	pink
15	`#FFCCAA`	`255, 204, 170`	light-peach

Names from Roman Zolotarev's PICO-8 palette reference, except:

"lavender" at index 13, as "indigo" is a darker, more saturated color, and also a somewhat different hue
"light-peach" at index 15, as "peach" seemed more appropriate in the additional color range below, which contains a dark peach color as well.

128..143: Undocumented extra colors

These colors are not documented, but zep has indicated that he is aware of their discovery and that he is allowing their use. Still, they remain undocumented, so it can't be assumed they will never change.

Index	Hex	RGB	Name
128	`#291814`	`41,24,20`	darkest-grey
129	`#111D35`	`17,29,53`	darker-blue
130	`#422136`	`66,33,54`	darker-purple
131	`#125359`	`18,83,89`	blue-green
132	`#742F29`	`116,47,41`	dark-brown
133	`#49333B`	`73,51,59`	darker-grey
134	`#A28879`	`162,136,121`	medium-grey
135	`#F3EF7D`	`243,239,125`	light-yellow
136	`#BE1250`	`190,18,80`	dark-red
137	`#FF6C24`	`255,108,36`	dark-orange
138	`#A8E72E`	`168,231,46`	lime-green
139	`#00B543`	`0,181,67`	medium-green
140	`#065AB5`	`6,90,181`	true-blue
141	`#754665`	`117,70,101`	mauve
142	`#FF6E59`	`255,110,89`	dark peach
143	`#FF9D81`	`255,157,129`	peach

Note that these colors were named arbitrarily at the time this section was created and are not official in any way. Those with a more artistic eye are invited to fine-tune them if they are off-base, but please try to keep in mind their connections to other parts of the palette, as has been done with the various grays, reds, greens, and blues. Knowing the exact name for a hue may not be as helpful to a reader as knowing where it can fit into a useful gradient.

All other unlisted system colors are currently black and should probably be treated as "reserved for future expansion", which is to say: do not use them.

Technical notes

System color indices are automatically masked with 0x8f, e.g. index &= 0x8f. This means that every set of 16 system colors between 0 and 127 (e.g. 32..47) is effectively the same as 0..15. Similarly, every set of 16 system colors between 128 and 255 is the same as 128..143.

In fact, this masking applies to all indices, including negative indices, since all other bits are masked off, resulting in 8 identical sets of the base colors alternating with 8 identical sets of the extra colors throughout the valid PICO-8 number range. This can be used to index 32 contiguous colors, most commonly centered around either 128 (112..143) or 0 (-16..15), depending on whether it is desired to have the base range or the extra range come first, respectively.