Pal

From Pico-8 Wiki
Jump to navigation Jump to search
pal( c0, c1, [p] )
Changes the draw state so all instances of a given color are replaced with a new color.
c0
The number of the original color to replace.

c1
The number of the new color to use instead.

p
0 to modify the palette used by draw operations, 1 to modify the palette for the screen already drawn, or 2 to modify the secondary screen palette. The default is 0.

All functions that draw to the screen, including spr() and map(), use the draw palette to decide which colors to write to the graphics buffer. The pal() function can modify this palette at any time to achieve certain effects, such as to temporarily replace a color used by a sprite with another color.

When the graphics buffer is copied to the screen (after _draw() executes or when the program calls flip()), it uses a screen palette. This gives the program another opportunity to replace colors for the entire graphics buffer for full screen effects such as fades, or perhaps very large explosions. You tell the pal() function to modify the screen palette by passing 1 as the optional third argument. Additionally, the secondary palette used by the fill pattern functionality and undocumented high-color modes can be modified by passing 2.

See Graphics for a table of color numbers.

To replace multiple colors at once, the pal() function may receive a single table argument optionally followed by the palette ID p. The key value of the entries in the table are the c0 values, and each entry's value are the c1 values. Any key outside the 0-15 range will be accepted, just that a modulo 16 will be applied to the key's number.

To reset the entire palette, call pal() without arguments. This also resets the transparency settings, as if you had also called palt() with no arguments, so it is not necessary to call both.

pal() is useful for a wide variety of effects. Just a few examples:

  • Use different colors with the same sprite to create multiple distinct instances, such as two figures wearing different clothes.
  • Embed multiple color patterns in a single sprite then change the palette to cause different patterns to appear for the same sprite, such as multiple kinds of wall tiles using the same sprite.
  • Animate color changes in one or more sprites to indicate status, such as a successful hit to an enemy, or a bomb about to explode.
  • Change the palette of an entire environment to indicate the time of day.

Examples

blink_frame = false
t = 0

function _update()
  -- every 8th frame is a "blink frame"
  t = (t + 1) % 8
  blink_frame = (t == 0)
end

function _draw()
  cls()

  -- reset the palette
  pal()

  if blink_frame then
    -- replace dark grey with red
    pal(5, 8)
  end

  -- draw the blinking light sprite
  spr(16, 56, 72)
end
Pal example.gif

See also