Palette

From Pico-8 Wiki
Jump to navigation Jump to search

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.

See also