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
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 Color Hex RGB Name 0
0, 0, 0
29, 43, 83
126, 37, 83
0, 135, 81
171, 82, 54
95, 87, 79
194, 195, 199
255, 241, 232
255, 0, 77
255, 163, 0
255, 236, 39
0, 228, 54
41, 173, 255
131, 118, 156
255, 119, 168
255, 204, 170
- 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 Color Hex RGB Name 128
- 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.
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.