PAL

pal = "palette" (set of colors)

 pal( color1, color2, [palette] )

 pal()  --reset

Calling pal with empty parentheses resets all colors to the default palette (including transparency settings):

Palette Types

0 = Draw Palette

Setting it to Draw Palette (using 0 or leaving it empty) will change the color palette for all future draws. Does not affect anything that was already drawn.

spr(1,10,10)  --draw red flower
pal(8,12,0)   --change reds to blue
spr(1,20,10)  --draw same flower

In the above code, we set color #8 (red) to be color #12 (blue), so when we draw the next same exact sprite, it will draw as blue instead, but does not affect the first flower. 

Even though we often refer to this function as "Palette Swap", note that it does not actually "swap" the colors around. Instead, it only replaces the first color with the second, while the second color remains the same. 

1 = Display Palette

Setting it to Display Palette (using 1) re-draws the whole screen before it gets displayed at the end of each frame. This will affect everything already drawn to the screen.

function _draw()
	cls()
	spr(1,10,10)  --draw red flower
	pal(8,12,1)   --change reds to blue
	spr(1,20,10)  --draw same flower
end

We can do the same demonstration as above, using a red flower sprite in sprite #1. However, the palette changes will reset when you exit the game. So we need to put this code inside of the _draw() function to stay in the game and view the changes. Press ESC and you will see the sprites turn back to the color red when the Display Palette gets reset.

Note that this also affects the editor colors. For example, if you type PAL(8,12,1) into the command line and press enter, all of the red (#8) immediately changes to blue (#12) even though it has already been drawn.

You can poke memory 0x5f2e and set it to 1 to force the palette to keep your changes so that both your game and the editors will maintain your palette changes.

poke( 0x5f2e, 1 )

2 = Secondary Palette

From the manual: "Used by FILLP() for drawing sprites. This provides a mapping from a single 4-bit colour index to two 4-bit colour indexes."

(to be expanded)

Reset Palette Type

 pal(#)  --pallete type to default

Calling pal with a single number (#0-2) will treat that as the palette type to reset to the default palette (including transparency settings).

Rearrange the Palette

 pal( table, [palette] )

Instead of the 2 color number arguments, it is also possible to pass a single table. This sets the full palette using a table of color numbers in order that they are arranged. 

 pal({15,14,13,12,11,10,9,8,7,6,5,4,3,2,1,0})

This will swap color numbers 1-15 (in order) to the numbers set within the table (reverse order). 

However, notice that color #0 did not change. That's because Lua tables start at 1 so the first number in the table will be set to color #1, and the next one #2, and so on, until #15. The 16th color in the table will be set to #0. 

If you would prefer the order of your table to start at #0, then you can force the table index number like this:

pal( { [0]=15, 14, 13, 12, 11, ... } )