How does kColorClear work with playdate.graphics.setBackgroundColor(color)

SDK Get Help
1

From Inside Playdate :
Use kColorClear if you intend to draw behind sprites.

What does it mean? Isn't the background always behind sprites? What can be behind the background to be shown when the background is clear?

2

Anything can be! You can draw directly to the screen, not just to sprites. So if your sprite background isn't clear, it will overwrite all that with solid white or black.

3

I still don't get it. What background is setBackgroundColor refering to? Is it the individual sprites' background? Is it the background sprite's background? Or is the screen's background?

I'm imagining the screen as a table. The table color is the background color. If I use a background sprite that is a piece of paper I cover the table with. The table still has its own color underneath. If I add sprites those are smaller paper cutouts I can put on top of the background paper, or directly on top of the table if I don't have a background paper. But I can never put anything below the table and see it through it (my table is opaque!)

4

The currently-set background color is used for various things, including clearing the screen (if you don't specify otherwise) and filling in extra margins revealed during a screen-shake effect.

In the case of sprites, it's used for a background that underlies all the sprites but is ON TOP of any graphics you have drawn directly to the screen.

Try the different values and you will see what works for your game. If you're using nothing BUT sprites, use whatever you want—but if other graphics need to show through, use clear.

5

Maybe it will be easier to understand with some code:

import 'CoreLibs/sprites.lua'
import 'CoreLibs/graphics.lua'
local gfx = playdate.graphics

function playdate.update()
  -- You can draw things directly without using sprites.
  gfx.setColor(gfx.kColorBlack)
  gfx.fillRect(15, 15, 20, 20)

  -- This function uses the background color to clear the screen,
  -- if background color is kColorClear, the rectangle drawn above
  -- will be visible. Otherwise it will be overdrawn here.
  gfx.sprite.update()
end