Pygame blit(): Draw Images and Surfaces on Screen

blit() copies one Surface onto another. screen.blit(image, (x, y)) draws image on the screen with its top-left corner at (x, y). Images, text and anything you drew on your own Surface all reach the screen through blit.

import pygame

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

player = pygame.image.load("assets/images/player.png").convert_alpha()
coin = pygame.image.load("assets/images/coin.png").convert_alpha()

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

    screen.fill((120, 190, 240))
    screen.blit(player, (60, 200))
    for i in range(5):
        screen.blit(coin, (180 + i * 50, 120))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

The images come from the free art pack these docs provide in an assets folder. On your computer, put PNG files next to your script and change the paths.

The arguments

screen.blit(source, dest, area=None, special_flags=0)

blit returns the Rect of the screen it changed, clipped to the screen.

Blitting at a Rect

Games usually keep a Rect for each object and blit at it. get_rect() with a keyword places the Rect, which makes centering easy:

import pygame

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

ship = pygame.image.load("assets/images/ship.png").convert_alpha()
rect = ship.get_rect(center=(240, 160))

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

    keys = pygame.key.get_pressed()
    rect.x += (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * 5
    rect.y += (keys[pygame.K_DOWN] - keys[pygame.K_UP]) * 5
    rect.clamp_ip(screen.get_rect())

    screen.fill((10, 12, 30))
    screen.blit(ship, rect)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Press Play, click the game and fly with the arrow keys.

Order matters

Each blit covers what is already there. Blit the background first, the player and enemies next, the score last. A screen.fill() after a blit wipes it out.

Part of an image: area

area copies only a rectangle of the source. It is one way to draw a single frame of a sprite sheet without cutting it first:

frame = pygame.Rect(24 * index, 0, 24, 24)
screen.blit(sheet, (100, 100), area=frame)

Animation uses subsurface for the same job, which cuts the frames once.

Many at once: blits()

screen.blits() takes a list of (source, dest) pairs and blits them all in one call, which saves some time when you draw hundreds of tiles:

screen.blits([(tile, (x * 36, y * 36)) for (x, y) in floor_cells])

Blending

special_flags mixes colors instead of covering them. pygame.BLEND_ADD adds the source's color to the screen's, which makes glows and light effects; pygame.BLEND_MULT darkens. Blending is not needed for normal drawing.