Lesson 1: The Game Loop

🛠️ Set Up pygame-ce

This course uses pygame-ce (pygame Community Edition), an actively maintained fork of the classic pygame library. You install it under the name pygame-ce, but your code still says import pygame, so almost every pygame tutorial on the web works with it too.

Open a terminal (Command Prompt or PowerShell on Windows, Terminal on macOS or Linux) and run the line for your system:

# Windows
py -m pip install pygame-ce

# macOS and Linux
python3 -m pip install pygame-ce

If you installed the original pygame for an older project, remove it first with python3 -m pip uninstall pygame (py -m pip uninstall pygame on Windows). The two packages share the name pygame inside Python, so having both installed causes confusing errors.

Now save this setup check as setup_check.py and run it:

import sys

import pygame

print("Python", sys.version.split()[0])
print("pygame", pygame.version.ver)
if getattr(pygame, "IS_CE", False):
    print("You have pygame-ce. You're ready!")
else:
    print("This is the original pygame, not pygame-ce.")
    print("Run: pip uninstall pygame   then: pip install pygame-ce")

The last line should read You have pygame-ce. You're ready!. pygame-ce also prints a one-line greeting with its version when it is imported; that is normal.

🎬 What Is a Game Loop?

A movie looks like smooth motion, but it is really a series of still pictures, usually 24 every second. Your brain blends them into movement. A game does the same thing with one big difference: it draws each picture on the spot, based on what you are doing right now. Each picture is called a frame, and the code that makes frames over and over is the game loop.

Every pass through the loop does the same three jobs, in the same order:

1. Handle events. Ask the operating system what happened since the last frame: key presses, mouse clicks, the window's close button.
2. Update. Change the game's state: move the player, run the enemies, check collisions, add to the score.
3. Draw. Paint the current state onto the screen, then show the finished picture.

Then the loop waits a moment, so it does not run faster than it needs to, and starts again.

🪟 Your First Window

Here is a complete pygame-ce program. Type it in (typing it teaches your fingers more than pasting does), save it as first_window.py, and run it. A dark window with a yellow circle should appear, and the close button should close it.

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
pygame.display.set_caption("My First Game Loop")
clock = pygame.time.Clock()

running = True
while running:
    clock.tick(60)                          # at most 60 frames per second

    # 1. Handle events
    for event in pygame.event.get():
        if event.type == pygame.QUIT:       # the window's close button
            running = False

    # 2. Update (nothing moves yet)

    # 3. Draw
    screen.fill((30, 30, 40))               # erase the last frame
    pygame.draw.circle(screen, (255, 200, 60), (400, 300), 40)
    pygame.display.flip()                   # show the finished frame

pygame.quit()

Read it from top to bottom:

• pygame.init() starts pygame's parts (display, fonts, sound). Call it once, before anything else.
• pygame.display.set_mode((800, 600)) opens an 800 × 600 pixel window and returns screen, the Surface (a picture in memory) you draw on.
• pygame.time.Clock() makes a clock that paces the loop. You will meet it properly in the next section.
• while running: is the game loop. It keeps going until something sets running = False.
• pygame.event.get() hands you every event that arrived since the last frame and empties the queue. Calling it every frame also tells the operating system your program is alive. The pygame docs warn that if you stop reading events for too long, the system may decide your program has locked up; that is when you see "Not Responding".
• screen.fill(color) paints the whole Surface one color, wiping out the previous frame. Colors are (red, green, blue) tuples, each from 0 to 255.
• pygame.display.flip() shows the finished Surface in the window all at once, so players never see a half-drawn frame.
• pygame.quit() runs after the loop ends and shuts pygame down cleanly.

⏱️ Frames, FPS and clock.tick()

FPS (frames per second) is how many times the loop runs each second. At 60 FPS, each frame gets 1000 ÷ 60 ≈ 16.7 milliseconds to handle events, update and draw.

clock.tick(60) does two jobs:

1. It caps the frame rate. If the frame finished early, tick waits for the rest of the 16.7 ms, so the loop runs at most 60 times a second. Without it, a simple loop runs as fast as the computer allows, keeping a CPU core busy drawing frames nobody can see. It is a cap, not a promise: if your frame takes 25 ms, you get 40 FPS.
2. It returns the time since the last tick, in milliseconds, as a whole number. That number is the key to the next section.

Call tick exactly once per loop. We put it first in the loop, so the frame time is ready before the update step needs it. clock.get_fps() gives the average frame rate over the last few frames, which is handy for an on-screen FPS counter.

🏃 Delta Time: The Same Speed Everywhere

The obvious way to move something is to add a few pixels every frame:

x += 4    # 4 pixels every frame: 240 px/s at 60 FPS, but only 120 px/s at 30 FPS

That works on your computer and breaks on everyone else's. On a laptop that only manages 30 FPS, the game runs in slow motion; on a 144 FPS machine, it runs more than twice as fast. Try it in the demo below: switch between frame rates and watch the red ball.

The fix is to think in pixels per second instead of pixels per frame. Each frame, ask how much time has passed, and move that fraction of a second's distance. That time is called delta time, or dt:

dt = clock.tick(60) / 1000    # milliseconds to seconds: about 0.0167 at 60 FPS
x += speed * dt               # pixels per second × seconds = pixels

At 60 FPS, dt is about 0.0167, so a ball with speed = 240 moves 4 pixels a frame. At 30 FPS, dt is about 0.033 and it moves 8 pixels a frame. Either way it covers 240 pixels every second. In this course, dt is always in seconds, speeds are in pixels per second, and timers count seconds.

Here is a complete program that slides a square across the window using dt:

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 200))
pygame.display.set_caption("Delta Time")
clock = pygame.time.Clock()

x = 0.0             # position in pixels (a float, so small steps add up)
speed = 240         # pixels per SECOND

running = True
while running:
    dt = clock.tick(60) / 1000          # seconds since the last frame
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    x += speed * dt
    if x > 800:                         # off the right edge?
        x -= 840                        # come back in from the left

    screen.fill((17, 24, 39))
    pygame.draw.rect(screen, (74, 222, 128), (x, 80, 40, 40))
    pygame.display.flip()

pygame.quit()

Change clock.tick(60) to clock.tick(20) and run it again. The square moves in bigger, choppier steps, but it crosses the window in the same time. That is frame-rate independence.

Notice that x starts as 0.0, a float. A step of 4.0 pixels adds up exactly, and so does a step of 1.7. If you stored the position in whole numbers, those fractions would be thrown away every frame and slow objects would stall.

🧰 Common Loop Problems

Every game developer hits these. Learn the symptom and you will fix them in seconds.

The last row deserves a closer look, because you will need it in the exercise. With dt, a fast ball can end a frame partly inside the wall. If you only flip its speed (vx = -vx), it may still be inside next frame, flip back, and get stuck buzzing along the wall. The reliable bounce does two things: put the ball back at the edge, and point it away from the wall with abs():

if x + BALL_RADIUS > WIDTH:     # poking out of the right edge
    x = WIDTH - BALL_RADIUS     # 1. put it back at the edge
    vx = -abs(vx)               # 2. always head left, whatever vx was

🏋️ Practice Exercise: Bouncing Ball Screensaver

"""Bouncing Ball Screensaver: Intro Lesson 1 practice exercise (solution).

A ball bounces around the window at the same speed at any frame rate,
and the current FPS is drawn in the corner. Close the window to quit.
"""
import pygame


WIDTH, HEIGHT = 800, 600
FPS = 60                        # try 30 and 144: the ball's speed should not change
BALL_RADIUS = 20
BG_COLOR = (20, 24, 36)
BALL_COLOR = (255, 107, 107)
TEXT_COLOR = (230, 230, 230)


def move_ball(x, y, vx, vy, dt):
    """Move the ball for one frame and bounce it off the window edges.

    vx and vy are speeds in pixels per SECOND and dt is in seconds.
    Returns the new (x, y, vx, vy).
    """
    x += vx * dt
    y += vy * dt

    # Bounce: push the ball back inside, then point it away from the wall.
    if x - BALL_RADIUS < 0:
        x = BALL_RADIUS
        vx = abs(vx)
    elif x + BALL_RADIUS > WIDTH:
        x = WIDTH - BALL_RADIUS
        vx = -abs(vx)
    if y - BALL_RADIUS < 0:
        y = BALL_RADIUS
        vy = abs(vy)
    elif y + BALL_RADIUS > HEIGHT:
        y = HEIGHT - BALL_RADIUS
        vy = -abs(vy)
    return x, y, vx, vy


def main():
    pygame.init()
    screen = pygame.display.set_mode((WIDTH, HEIGHT))
    pygame.display.set_caption("Bouncing Ball Screensaver")
    clock = pygame.time.Clock()
    font = pygame.font.Font(None, 32)       # create fonts once, before the loop

    x, y = WIDTH / 2, HEIGHT / 2
    vx, vy = 240.0, 180.0                   # pixels per second
    frames = 0
    seconds = 0.0

    running = True
    while running:
        dt = clock.tick(FPS) / 1000         # seconds since the last frame

        # 1. Handle events
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False

        # 2. Update
        x, y, vx, vy = move_ball(x, y, vx, vy, dt)
        frames += 1
        seconds += dt

        # 3. Draw
        screen.fill(BG_COLOR)
        pygame.draw.circle(screen, BALL_COLOR, (x, y), BALL_RADIUS)
        fps_text = font.render(f"FPS: {clock.get_fps():.0f}", True, TEXT_COLOR)
        screen.blit(fps_text, (10, 10))
        pygame.display.flip()

    pygame.quit()
    print(f"Drew {frames} frames in {seconds:.1f} seconds.")


if __name__ == "__main__":
    main()

📓 Learning Journal

📝 Summary

You installed pygame-ce and opened your first game window. Behind that window is the game loop: each frame it handles events, updates the game and draws a fresh picture, then waits so it does not run faster than it needs to. You learned that clock.tick() both caps the frame rate and reports how long the last frame took, and you used that time, dt, to move a ball in pixels per second, so it plays the same on a slow laptop and a fast gaming PC.

🔭 Looking Ahead

Your loop draws one circle. In the next lesson, Drawing Shapes & Surfaces, you fill the frame with rectangles, lines, polygons and text, and learn how Surfaces let you build a picture once and draw it many times.

❓ Common Questions

🎯 Quick Quiz

🌟 Going Further

• Two balls: add a second ball with its own position, speed and color. Give each ball its own x, y, vx, vy and call move_ball() for both.
• Gravity: add vy += 980 * dt before moving, so the ball falls and bounces like a real one. (980 pixels per second squared feels about right on screen.)
• Slow motion: multiply dt by 0.25 before using it. The whole game slows down smoothly, which is how many games do a slow-motion effect.
• Read the docs: skim the pygame-ce pages for pygame.time (Clock), pygame.display and pygame.event. Find one function you haven't used yet.
• Coming up in Game Dev II: Intermediate: Velocity, Acceleration & Timesteps builds a true fixed-timestep loop for physics that plays out the same way every time.