Introduction to Pygame

last modified February 25, 2025

Pygame is a popular Python library for creating 2D games and multimedia applications. It provides tools for handling graphics, sound, and user input, making it an excellent choice for beginners in game development. This tutorial covers the basics of setting up a Pygame window and handling events.

Pygame is built on top of the SDL (Simple DirectMedia Layer) library, which provides low-level access to audio, keyboard, mouse, and display hardware. With Pygame, you can create games and interactive applications with ease.

Installing Pygame

Before using Pygame, you need to install it. You can install Pygame using pip:

install_pygame.sh

pip install pygame

Once installed, you can start creating games with Pygame.

Setting Up a Pygame Window

This example demonstrates how to create a basic Pygame window.

basic_window.py

import pygame

Initialize Pygame

pygame.init()

Set up the display

screen = pygame.display.set_mode((800, 600)) pygame.display.set_caption(“Pygame Window”)

Main loop

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

# Fill the screen with a color
screen.fill((0, 0, 0))

# Update the display
pygame.display.flip()

pygame.quit()

The pygame.init function initializes all Pygame modules. The pygame.display.set_mode function creates a window of the specified size. The main loop handles events and updates the display.

Handling Events

This example demonstrates how to handle keyboard and mouse events in Pygame.

event_handling.py

import pygame

Initialize Pygame

pygame.init()

Set up the display

screen = pygame.display.set_mode((800, 600)) pygame.display.set_caption(“Event Handling”)

Main loop

running = True while running: for event in pygame.event.get(): if event.type == pygame.QUIT: running = False elif event.type == pygame.KEYDOWN: if event.key == pygame.K_ESCAPE: running = False print(f"Key pressed: {pygame.key.name(event.key)}") elif event.type == pygame.MOUSEBUTTONDOWN: print(f"Mouse button pressed at: {event.pos}")

# Fill the screen with a color
screen.fill((0, 0, 0))

# Update the display
pygame.display.flip()

pygame.quit()

The pygame.event.get function retrieves all events from the event queue. Keyboard and mouse events are handled using pygame.KEYDOWN and pygame.MOUSEBUTTONDOWN.

Drawing Shapes

This example demonstrates how to draw shapes on the screen.

drawing_shapes.py

import pygame

Initialize Pygame

pygame.init()

Set up the display

screen = pygame.display.set_mode((800, 600)) pygame.display.set_caption(“Drawing Shapes”)

Main loop

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

# Fill the screen with a color
screen.fill((255, 255, 255))

# Draw a rectangle
pygame.draw.rect(screen, (255, 0, 0), (100, 100, 200, 150))

# Draw a circle
pygame.draw.circle(screen, (0, 255, 0), (400, 300), 75)

# Draw a line
pygame.draw.line(screen, (0, 0, 255), (700, 100), (700, 500), 5)

# Update the display
pygame.display.flip()

pygame.quit()

The pygame.draw.rect, pygame.draw.circle, and pygame.draw.line functions are used to draw shapes on the screen.

Bouncing ball

In the next example, we create a bouncing ball animation.

anim_ball.py

import pygame

Initialize Pygame

pygame.init()

Set up the display

screen = pygame.display.set_mode((800, 600)) pygame.display.set_caption(“Bouncing Ball”)

Ball properties

ball_color = (255, 255, 255) ball_radius = 20 ball_x = 400 ball_y = 300 ball_x_speed = 5

clock = pygame.time.Clock()

ball_y_speed = 5

Main loop

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

# Ball movement
ball_x += ball_x_speed
ball_y += ball_y_speed

# Bounce off the walls
if ball_x + ball_radius > 800 or ball_x - ball_radius < 0:
    ball_x_speed *= -1
if ball_y + ball_radius > 600 or ball_y - ball_radius < 0:
    ball_y_speed *= -1

# Fill the screen with a color
screen.fill((0, 0, 0))

# Draw the ball
pygame.draw.circle(screen, ball_color, (int(ball_x), int(ball_y)), ball_radius)

clock.tick(60)

# Update the display
pygame.display.flip()

pygame.quit()

The ball’s properties are defined, including its color, radius, initial position, and speed. The main loop of the program runs while the running variable is True. Within this loop, it checks for events (like quitting the program) and updates the ball’s position based on its speed. If the ball hits the edge of the window, it bounces back by reversing its speed.

The screen is then filled with a black color, and the ball is drawn at its updated position using pygame.draw.circle. The program ensures that the display updates at a rate of 60 frames per second by using clock.tick(60), and finally, the display is updated with pygame.display.flip. When the main loop ends, Pygame is quit with pygame.quit.

Best Practices for Pygame

• Initialize Pygame Properly: Always call pygame.init at the start of your program.

• Handle Events Efficiently: Use the event loop to handle user input and other events.

• Use Double Buffering: Use pygame.display.flip to update the display efficiently.

• Clean Up Resources: Call pygame.quit to clean up resources when your program ends.

Source

Pygame Documentation

In this article, we have explored the basics of Pygame, including setting up a window, handling events, drawing shapes, and moving a ball.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Python tutorials.