pygame.draw: Rectangles, Circles, Lines and Polygons

pygame.draw draws shapes onto a Surface, usually the screen. Every function takes the surface first, then a color, then where to draw:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 360))
clock = pygame.time.Clock()
running = True

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

    screen.fill((245, 240, 230))
    pygame.draw.rect(screen, (230, 80, 80), (30, 30, 120, 80))
    pygame.draw.rect(screen, (40, 40, 40), (180, 30, 120, 80), width=4)
    pygame.draw.rect(screen, (80, 160, 240), (330, 30, 120, 80), border_radius=16)
    pygame.draw.circle(screen, (250, 190, 40), (90, 200), 50)
    pygame.draw.circle(screen, (40, 160, 90), (240, 200), 50, width=8)
    pygame.draw.ellipse(screen, (170, 90, 220), (330, 160, 120, 80))
    pygame.draw.line(screen, (40, 40, 40), (30, 300), (450, 300), 3)
    pygame.draw.polygon(screen, (255, 140, 0), [(240, 260), (270, 340), (210, 340)])
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

The functions

width: filled or outline

For rect, circle, ellipse and polygon, width=0 (the default) fills the shape. Any other value draws only an outline that many pixels thick. Lines always use width as their thickness.

Rectangles

A rectangle is placed by its top-left corner plus its width and height. You can pass a tuple, but games usually keep a pygame.Rect, which also moves and checks collisions (see Pygame Rect):

player = pygame.Rect(100, 80, 40, 60)
pygame.draw.rect(screen, "orange", player)

border_radius rounds all four corners. Each corner can also differ: border_top_left_radius, border_top_right_radius, border_bottom_left_radius and border_bottom_right_radius.

Circles

A circle is placed by its center, not its corner. That is the most common surprise: pygame.draw.circle(screen, color, (0, 0), 30) shows only a quarter circle in the window's corner.

Drawing order

Later drawings cover earlier ones. Draw the background first and the things in front last, and call screen.fill() at the start of the frame, never after drawing. Every pygame.draw function returns the Rect it changed, which is handy for collisions and for partial screen updates.

A scene from shapes

Shapes plus a loop are already enough for a moving picture. This one draws a house, a tree and a car that drives past:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 360))
clock = pygame.time.Clock()
car_x = -100
running = True

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

    car_x = car_x + 3 if car_x < 500 else -100

    screen.fill((150, 210, 250))
    pygame.draw.rect(screen, (90, 170, 80), (0, 260, 480, 100))
    pygame.draw.rect(screen, (90, 90, 100), (0, 300, 480, 40))
    # house
    pygame.draw.rect(screen, (230, 200, 160), (60, 160, 120, 100))
    pygame.draw.polygon(screen, (180, 60, 50), [(50, 160), (120, 100), (190, 160)])
    pygame.draw.rect(screen, (120, 80, 50), (105, 210, 30, 50))
    # tree
    pygame.draw.rect(screen, (110, 70, 40), (330, 190, 20, 70))
    pygame.draw.circle(screen, (40, 130, 60), (340, 170), 45)
    # car
    pygame.draw.rect(screen, (220, 50, 60), (car_x, 280, 90, 30), border_radius=6)
    pygame.draw.rect(screen, (220, 50, 60), (car_x + 20, 262, 50, 22), border_radius=6)
    pygame.draw.circle(screen, (30, 30, 30), (car_x + 20, 312), 10)
    pygame.draw.circle(screen, (30, 30, 30), (car_x + 70, 312), 10)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Shapes are quick to draw and need no files, which makes them good for prototypes. When you want art, load images and blit them instead.