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 Color Hex RGB Name 0 #0000000, 0, 0black 1 #1D2B5329, 43, 83dark-blue 2 #7E2553126, 37, 83dark-purple 3 #0087510, 135, 81dark-green 4 #AB5236171, 82, 54brown 5 #5F574F95, 87, 79dark-grey 6 #C2C3C7194, 195, 199light-grey 7 #FFF1E8255, 241, 232white 8 #FF004D255, 0, 77red 9 #FFA300255, 163, 0orange 10 #FFEC27255, 236, 39yellow 11 #00E4360, 228, 54green 12 #29ADFF41, 173, 255blue 13 #83769C131, 118, 156lavender 14 #FF77A8255, 119, 168pink 15 #FFCCAA255, 204, 170light-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.
Note that the 16-color palettes repeat in the lo and hi ranges, such that 0..15 is the same as 16..31, and so on up to 112..127, and likewise 128..143 is the same as each 16-color palette up to 240..255.
Additionally, PICO-8 only uses the bottom 8 bits of a palette index, so it's possibly to pass in negative values that will map to the hi range once the extra bits are ignored, e.g. -1 is 0xffff, which clips to 0x00ff or 255. Thus it may be convenient to use values -16..-1 instead of 128..143, depending on circumstances, especially since it makes the entire 32-color hardware palette contiguous in the range -16..15.
Index Color Hex RGB Name 128 / -16 #29181441,24,20brownish-black 129 / -15 #111D3517,29,53darker-blue 130 / -14 #42213666,33,54darker-purple 131 / -13 #12535918,83,89blue-green 132 / -12 #742F29116,47,41dark-brown 133 / -11 #49333B73,51,59darker-grey 134 / -10 #A28879162,136,121medium-grey 135 / -9 #F3EF7D243,239,125light-yellow 136 / -8 #BE1250190,18,80dark-red 137 / -7 #FF6C24255,108,36dark-orange 138 / -6 #A8E72E168,231,46lime-green 139 / -5 #00B5430,181,67medium-green 140 / -4 #065AB56,90,181true-blue 141 / -3 #754665117,70,101mauve 142 / -2 #FF6E59255,110,89dark-peach 143 / -1 #FF9D81255,157,129peach
- 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.
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.