Pygame Setup Guide

Pygame lets you build games and visual simulations with Python. You get a window, the ability to draw shapes and images, handle keyboard and mouse input, and play sounds. If you have ever wanted to make a game, this is a great way to start.

No game development experience is needed. Pygame handles the graphics and input — you write the logic that makes your game work.

Quick Setup

If you have not used uv before, review the Packages and uv guide first.

Open your terminal, navigate to your project folder, and run:

uv init
uv add pygame-ce

We use pygame-ce (Community Edition) instead of the original pygame package. It is actively maintained, faster, and fully compatible. You still import it as pygame in your code.

Create a file called game.py:

import pygame

pygame.init()

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

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

    screen.fill("black")

    pygame.draw.circle(screen, "blue", (400, 300), 40)

    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Run it:

uv run python game.py

You should see a window with a blue circle on a black background. Close the window or press Ctrl+C in your terminal to quit.

How Pygame Works

Every Pygame program follows the same pattern: the game loop. This loop runs many times per second (typically 60 times) and does three things each frame:

  1. Handle events — check for keyboard presses, mouse clicks, and the window close button
  2. Update state — move objects, check collisions, update scores
  3. Draw everything — clear the screen, draw all objects in their new positions, then flip the display
while running:
    # 1. Handle events
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    # 2. Update state
    x += speed

    # 3. Draw
    screen.fill("black")
    pygame.draw.rect(screen, "red", (x, y, 50, 50))
    pygame.display.flip()
    clock.tick(60)

The clock.tick(60) call limits the loop to 60 frames per second so your game runs at a consistent speed.

Handling Input

Pygame gives you two ways to read keyboard input:

Event-based — fires once when a key is pressed or released. Good for menus, jumping, shooting.

for event in pygame.event.get():
    if event.type == pygame.KEYDOWN:
        if event.key == pygame.K_SPACE:
            player_jump()

State-based — checks if a key is currently held down. Good for movement.

keys = pygame.key.get_pressed()
if keys[pygame.K_LEFT]:
    player_x -= 5
if keys[pygame.K_RIGHT]:
    player_x += 5

my-project/
├── game.py             # Main file (game loop, rendering)
├── logic.py            # Your business logic (game rules, scoring, physics)
├── assets/             # Images, sounds, fonts
│   ├── player.png
│   └── ...
├── data/               # Level data, high scores, config
├── pyproject.toml      # Dependencies (created by uv)
└── README.md

Put your game loop and drawing code in game.py. Put your game rules, collision detection, scoring, and any algorithms in logic.py. This separation matters — the logic in logic.py is the code you should understand deeply and be ready to explain.

Project Ideas

Here are some ideas that are realistic for a 3-week timeline. Start with the simplest version that is playable, then add features.

Snake — The classic. Control a snake that grows when it eats food. Game over when you hit the walls or yourself. MVP: a moving snake that eats one food item at a time, grows longer, and ends when it hits a wall.

Pong — Two paddles, one ball. Can be single-player (vs. a simple AI) or two-player (shared keyboard). MVP: one paddle controlled by the player, one that follows the ball, a bouncing ball, and a score counter.

Top-Down Maze Runner — Navigate a character through a maze. Generate the maze from a grid or load it from a file. MVP: a player that moves through a hardcoded maze, with walls that block movement, and a goal to reach.

Particle Simulation — Simulate particles that move, bounce, attract, or repel each other. Great if you are interested in physics or generative art. MVP: particles that spawn, move with velocity, and bounce off the edges of the window.

Simple Platformer — A character that can run and jump across platforms. MVP: a player with gravity, a few static platforms, and left/right/jump controls.

Tutorials and Resources

Agent Prompts

Use these prompts with your coding agent (Cursor, Claude Code, etc.) to get started. Copy and paste them, then modify to fit your project.

Plan your game:

Read my project.spec.md. I want to build a [type of game] using Pygame. Help me think through what objects I need (player, enemies, items, etc.), what the game loop should do each frame, and what the simplest playable version looks like. Ask me questions to help narrow down the scope.

Scaffold your project:

Read my project.spec.md and set up my Pygame project. Create game.py with the basic game loop, a window, and a placeholder player object I can move with arrow keys. Create logic.py with a simple function for the game rules. Explain how the game loop works so I understand the structure.

Add a game mechanic:

Look at my game.py. I want to add [describe the mechanic — collision detection, scoring, enemies, etc.]. Show me how to implement it and put the core logic in logic.py. Explain how it works step by step so I can modify it later.

Debug a visual issue:

My game is running but [describe the problem — the player is not showing up, things are flickering, movement is too fast, etc.]. Look at my game.py and help me figure out what is wrong. Explain what is happening in the game loop that causes this and how to fix it.