Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 41 ยท Drawing and Images

Drawing Shapes in Pygame

Draw with pygame.draw - filled and outlined rectangles, rounded corners, circles, ellipses, lines, polygons and arcs. Learn line width, antialiasing and animated colors.

Before you have any artwork, shapes are enough to make a whole game: Pong, Snake, Breakout and many puzzle games need nothing more than rectangles and circles. The pygame.draw module draws shapes straight onto any Surface, the screen or an off-screen one. This lesson covers every shape, the meaning of the width argument, rounded rectangles and a few drawing patterns.

All functions share the same beginning: the surface to draw on, a color, and the geometry. They return the bounding Rect of the pixels they changed.

Python
pygame.draw.rect(screen, color, rect, width=0, border_radius=0)
pygame.draw.circle(screen, color, center, radius, width=0)
pygame.draw.ellipse(screen, color, rect, width=0)
pygame.draw.line(screen, color, start, end, width=1)
pygame.draw.lines(screen, color, closed, points, width=1)
pygame.draw.polygon(screen, color, points, width=0)
pygame.draw.arc(screen, color, rect, start_angle, stop_angle, width=1)
pygame.draw.aaline(screen, color, start, end)      # antialiased (smooth) line

The width argument

For filled-capable shapes, width=0 (the default) means filled. A positive width draws only an outline of that many pixels. Lines use width as their thickness.

Python
pygame.draw.rect(screen, WHITE, (50, 50, 120, 80))            # filled
pygame.draw.rect(screen, WHITE, (50, 50, 120, 80), 3)         # 3 px outline

Rectangles

The rect argument can be a Rect or a 4-tuple (x, y, width, height). This is where it is easy to mix up the arguments: the third and fourth numbers are the size, not a second corner.

Python
pygame.draw.rect(screen, (200, 60, 60), pygame.Rect(40, 40, 160, 90))

Rounded corners come from border_radius:

Python
pygame.draw.rect(screen, (60, 120, 220), (40, 160, 160, 90), border_radius=20)
pygame.draw.rect(screen, (255, 255, 255), (40, 160, 160, 90), width=3, border_radius=20)

You can round only some corners with border_top_left_radius, border_top_right_radius, border_bottom_left_radius and border_bottom_right_radius: useful for tabs and speech bubbles. A health bar is simply two rectangles, one for the background and a shorter one on top:

Python
def draw_health_bar(surface, x, y, width, height, fraction):
    pygame.draw.rect(surface, (60, 60, 60), (x, y, width, height))
    pygame.draw.rect(surface, (80, 200, 90), (x, y, int(width * fraction), height))

Circles, ellipses and arcs

circle takes a center point and a radius (not a diameter and not a rect). ellipse fits inside a rect. arc draws part of an ellipse between two angles in radians (0 is to the right, counter-clockwise):

Python
import math
pygame.draw.circle(screen, YELLOW, (300, 200), 40)
pygame.draw.ellipse(screen, GREEN, (100, 300, 160, 60), 2)
pygame.draw.arc(screen, WHITE, (350, 250, 120, 120), 0, math.pi, 3)    # top half

circle also accepts draw_top_right=True and friends to draw a single quarter, handy for pie-style charts and rounded decorations.

Lines and polygons

Python
pygame.draw.line(screen, WHITE, (0, 0), (200, 100), 4)
pygame.draw.lines(screen, WHITE, False, [(10, 200), (60, 150), (110, 200)], 2)   # open path
pygame.draw.polygon(screen, RED, [(300, 100), (350, 200), (250, 200)])           # triangle

For lines, the boolean says whether to close the shape back to the first point. Thick lines with a large width can look uneven at their ends and joints; for smooth thin lines use aaline or aalines, which are antialiased but always one pixel wide.

Draw on an off-screen surface and print it as text. Each letter marks a different shape, so you can see how filled and outlined versions differ.

Python Shapes as ASCII art

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Return values and the dirty rect

Each draw function returns a Rect covering the affected area. You rarely need it, but it is useful for updating only part of the display or for hit boxes:

Python What draw functions return

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Animated color: a breathing effect

Colors can change over time. A sine wave gives a smooth pulse; feeding it into Color.lerp blends between two colors. In a real game you would compute it each frame from pygame.time.get_ticks():

Python
import math
t = pygame.time.get_ticks() / 1000
amount = (math.sin(t * 2) + 1) / 2          # 0..1
color = dark.lerp(bright, amount)
screen.fill(color)
Python Breathing color values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Drawing tips

  • Draw from back to front: background, shapes, text.
  • Clear the screen with fill at the start of each frame, or old frames leave trails.
  • Shapes are not objects. Once drawn they are just pixels. Keep positions in variables or sprites and redraw every frame.
  • For many static shapes, draw them once onto a Surface and blit that Surface each frame.
  • Large width values on circles draw rings; width larger than the radius is clamped.
  • Outlines are drawn inside the shape's rectangle, so the outer size does not change when you add a border.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does width=0 mean for pygame.draw.rect?

    Width 0 fills the shape. A positive width draws an outline of that thickness.
  2. 2. What does the third argument of pygame.draw.circle(screen, color, center, radius) represent?

    The arguments are surface, color, center, radius. The center comes before the radius.
  3. 3. Which keyword rounds the corners of a drawn rectangle?

    pygame.draw.rect(..., border_radius=20) rounds all corners.
  4. 4. In what unit does pygame.draw.arc expect its angles?

    Use math.radians() or constants like math.pi for angles.
  5. 5. Why do old frames leave trails?

    Pygame keeps what is already on the surface. Clear at the start of each frame.

Summary

  • pygame.draw provides rect, circle, ellipse, line(s), aaline, polygon and arc.
  • width=0 fills; a positive width outlines (or sets line thickness).
  • Use border_radius for rounded rectangles.
  • Angles are in radians; circles take a radius.
  • Draw functions return the affected Rect.
  • Clear and redraw every frame; sine waves plus lerp give smooth color animation.

Next: Text and Fonts