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 Color 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.
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 #291814
41,24,20
brownish-black 129 / -15 #111D35
17,29,53
darker-blue 130 / -14 #422136
66,33,54
darker-purple 131 / -13 #125359
18,83,89
blue-green 132 / -12 #742F29
116,47,41
dark-brown 133 / -11 #49333B
73,51,59
darker-grey 134 / -10 #A28879
162,136,121
medium-grey 135 / -9 #F3EF7D
243,239,125
light-yellow 136 / -8 #BE1250
190,18,80
dark-red 137 / -7 #FF6C24
255,108,36
dark-orange 138 / -6 #A8E72E
168,231,46
lime-green 139 / -5 #00B543
0,181,67
medium-green 140 / -4 #065AB5
6,90,181
true-blue 141 / -3 #754665
117,70,101
mauve 142 / -2 #FF6E59
255,110,89
dark-peach 143 / -1 #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.
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.