Your First Pygame Program: Open a Window

Your first pygame program opens a window, draws something in it and stays open until you close it. It is about fifteen lines, and almost every pygame game starts with the same ones.

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 360))
pygame.display.set_caption("My first game")
clock = pygame.time.Clock()
running = True

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

    screen.fill((135, 206, 235))
    pygame.draw.circle(screen, (255, 220, 0), (400, 70), 40)
    pygame.draw.rect(screen, (60, 160, 60), (0, 280, 480, 80))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Press Play to see a sky, a sun and some grass. Change the numbers and press Play again.

Line by line

import pygame loads the library. pygame.init() starts all of its modules (display, fonts, sound) in one call.

screen = pygame.display.set_mode((480, 360)) opens a window 480 pixels wide and 360 tall and returns a Surface, an image you can draw on. Everything your game shows is drawn on screen. Note the double parentheses: the size is one tuple.

pygame.display.set_caption(...) sets the window title.

clock = pygame.time.Clock() makes a clock that keeps the game at a steady speed.

while running: is the game loop. Each pass draws one frame. Without it the program would reach its end and the window would close at once.

for event in pygame.event.get(): reads everything that happened since the last frame: key presses, mouse clicks, and the window's close button, which arrives as a pygame.QUIT event. Setting running = False ends the loop.

screen.fill(...) paints the whole screen one color, wiping out the last frame. The colors are (red, green, blue) numbers from 0 to 255; see pygame colors.

pygame.draw.circle and pygame.draw.rect draw the sun and the grass. The pygame.draw page has every shape.

pygame.display.flip() shows the finished frame. Pygame draws into a hidden buffer, and nothing appears in the window until you flip it.

clock.tick(60) waits so the loop runs at most 60 times a second.

pygame.quit() shuts pygame down after the loop ends.

Coordinates

Pygame measures in pixels from the top-left corner of the window. x grows to the right and y grows down, unlike the graphs from math class. In a 480 by 360 window:

That is why the grass starts at y = 280: it is near the bottom.

Make something move

A frame is redrawn sixty times a second, so changing a number a little each frame makes something move. This version moves the sun across the sky:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 360))
pygame.display.set_caption("Sunrise")
clock = pygame.time.Clock()
sun_x = 0
running = True

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

    sun_x += 2
    if sun_x > 520:
        sun_x = -40

    screen.fill((135, 206, 235))
    pygame.draw.circle(screen, (255, 220, 0), (sun_x, 70), 40)
    pygame.draw.rect(screen, (60, 160, 60), (0, 280, 480, 80))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Try removing the screen.fill(...) line: the sun leaves a trail, because the old frames are never painted over.

Next steps

The loop you just wrote is the heart of every pygame game. The game loop explains its three parts, and keyboard input lets the player take control.