The Pygame Game Loop Explained

A pygame game is a loop. Each time around it the game does three things, then shows the result:

1. Handle events: read what the player did (keys, mouse, the close button).
2. Update: move things, apply the rules, check collisions.
3. Draw: paint the new frame, then flip() it onto the screen.

clock.tick(60) at the end holds the loop to 60 frames a second. Here are the three steps in a small game: a ball falls, and Space throws it back up.

import pygame

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

y = 50.0
speed = 0.0
running = True

while running:
    # 1. Handle events
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE:
            speed = -9

    # 2. Update
    speed += 0.4
    y += speed
    if y > 320:
        y = 320
        speed = -speed * 0.6

    # 3. Draw
    screen.fill((24, 26, 40))
    pygame.draw.line(screen, (90, 90, 120), (0, 340), (480, 340), 2)
    pygame.draw.circle(screen, (255, 120, 80), (240, int(y)), 20)
    pygame.display.flip()

    clock.tick(60)

pygame.quit()

Press Play, click the game, then press Space.

Why the order matters

Events first, so this frame reacts to what the player just did. If you read input after drawing, the game lags one frame behind the keyboard.

Update before draw, so the frame shows the new state. Drawing first would show where things were, not where they are.

Fill, draw, flip. Start each frame by clearing the screen (screen.fill), draw the background first and the player last (later drawings cover earlier ones), and call pygame.display.flip() exactly once at the end. Pygame draws into a hidden buffer; the window shows nothing new until the flip.

Reading events every frame

The for event in pygame.event.get() loop does more than notice keys. It also tells the operating system that your window is alive. A loop that never calls pygame.event.get() (or pygame.event.pump()) gets a "Not Responding" window on Windows and a spinning cursor on macOS, and the close button stops working. Keep the event loop even in a program that ignores input.

Ending the loop

The running flag is the usual way to stop: the QUIT event sets it to False, the loop finishes its pass, and pygame.quit() runs after it. A game can also end the loop from its own rules, for example when the player presses Escape:

if event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
    running = False

Avoid calling pygame.quit() inside the loop. The loop would carry on to screen.fill() with pygame shut down and stop with pygame.error: video system not initialized.

A game class

As a game grows, the loop is easier to read as a class with one method per step. The structure is the same:

import pygame


class Game:
    def __init__(self):
        pygame.init()
        self.screen = pygame.display.set_mode((480, 360))
        pygame.display.set_caption("Game class")
        self.clock = pygame.time.Clock()
        self.player = pygame.Rect(220, 160, 40, 40)
        self.running = True

    def handle_events(self):
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                self.running = False

    def update(self):
        keys = pygame.key.get_pressed()
        dx = keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]
        dy = keys[pygame.K_DOWN] - keys[pygame.K_UP]
        self.player.move_ip(dx * 5, dy * 5)
        self.player.clamp_ip(self.screen.get_rect())

    def draw(self):
        self.screen.fill((20, 40, 30))
        pygame.draw.rect(self.screen, (120, 230, 120), self.player)
        pygame.display.flip()

    def run(self):
        while self.running:
            self.handle_events()
            self.update()
            self.draw()
            self.clock.tick(60)
        pygame.quit()


Game().run()

keys[pygame.K_RIGHT] - keys[pygame.K_LEFT] is a short way to get 1, -1 or 0 for the direction, because a pressed key counts as True (1).

Next

Pygame Clock explains tick(), frame rates and delta time, and Pygame events covers everything the event loop can read.