Pygame Colors: RGB Tuples, Names and pygame.Color

A color in pygame is three numbers: how much red, green and blue light to mix, each from 0 (none) to 255 (full). (255, 0, 0) is red, (0, 0, 0) is black and (255, 255, 255) is white.

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 300))
clock = pygame.time.Clock()

swatches = [
    (255, 0, 0),          # a tuple
    (0, 200, 120),
    "gold",               # a name
    "skyblue",
    "#ff66cc",            # a hex string
    pygame.Color(120, 80, 255),
]

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    screen.fill("white")
    for i, color in enumerate(swatches):
        pygame.draw.rect(screen, color, (20 + i * 76, 100, 64, 100), border_radius=8)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Every function that takes a color (fill, pygame.draw, font.render) accepts all of these forms.

Three ways to write a color

Some mixes worth knowing: equal red, green and blue is a gray ((128, 128, 128)); red plus green is yellow; red plus blue is purple; green plus blue is cyan.

Many games keep their colors as constants at the top of the file, so they are easy to change:

BACKGROUND = (24, 26, 40)
PLAYER = (255, 196, 0)
ENEMY = (230, 70, 70)

pygame.Color

pygame.Color is a color object. It takes any of the forms above and gives you its parts and some useful methods:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 200))
clock = pygame.time.Clock()

sky = pygame.Color("skyblue")
night = pygame.Color(10, 10, 40)
print(sky.r, sky.g, sky.b)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    for x in range(480):
        color = sky.lerp(night, x / 479)
        pygame.draw.line(screen, color, (x, 0), (x, 199))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

135 206 235

a.lerp(b, t) blends from a at t = 0 to b at t = 1, which draws the gradient above. A Color also has .a (alpha), .hsva for hue, saturation and value, and supports +, - and * per channel, clamped to 0 to 255.

Transparency (alpha)

A fourth number, alpha, sets how opaque a color is: 255 is solid, 0 is invisible. The screen itself has no transparency, so to see alpha work you draw on a Surface made with pygame.SRCALPHA and then blit it:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 300))
clock = pygame.time.Clock()

glass = pygame.Surface((200, 140), pygame.SRCALPHA)
glass.fill((255, 255, 255, 90))

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    screen.fill((30, 60, 110))
    pygame.draw.circle(screen, "orange", (240, 150), 80)
    screen.blit(glass, (140, 80))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

The white panel lets the circle show through. Pygame Surface covers SRCALPHA, set_alpha() and color keys in detail.

Invalid colors

A color pygame cannot read stops the program:

ValueError: invalid color (color sequence must have size 3 or 4, and each element must be an integer in the range [0, 255])

The usual causes are a tuple with two values, or a computed value that went over 255 or below 0, such as a color that fades a little every frame. Keep computed values in range with max(0, min(255, value)). A misspelled name gives ValueError: invalid color name.