Pygame Collision Detection: colliderect and More

Most pygame games detect collisions with rectangles. Give every object a pygame.Rect, move it, then ask the Rect whether it overlaps another:

import random
import pygame

pygame.init()
screen = pygame.display.set_mode((480, 360))
clock = pygame.time.Clock()
font = pygame.font.Font(None, 32)

player = pygame.Rect(220, 300, 40, 40)
coin = pygame.Rect(random.randint(0, 456), random.randint(0, 200), 24, 24)
score = 0
running = True

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

    keys = pygame.key.get_pressed()
    player.x += (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * 5
    player.y += (keys[pygame.K_DOWN] - keys[pygame.K_UP]) * 5
    player.clamp_ip(screen.get_rect())

    if player.colliderect(coin):
        score += 1
        coin.topleft = (random.randint(0, 456), random.randint(0, 336))

    screen.fill((25, 30, 45))
    pygame.draw.ellipse(screen, (255, 210, 60), coin)
    pygame.draw.rect(screen, (90, 200, 255), player)
    screen.blit(font.render(f"Score: {score}", True, "white"), (10, 10))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Press Play, click the game and collect coins with the arrow keys. When the boxes overlap, the coin jumps somewhere new.

Rect collision methods

Rectangles that only share an edge do not count as overlapping. For collisions between sprites in groups, see sprite collisions.

Stopping at a wall

Detecting a collision is half the job; often the player must also not pass through. The reliable way is to move and fix one axis at a time. After moving on x, any overlap must have come from horizontal movement, so you know which edge to push back:

import pygame

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

walls = [
    pygame.Rect(0, 0, 480, 16),
    pygame.Rect(0, 344, 480, 16),
    pygame.Rect(0, 0, 16, 360),
    pygame.Rect(464, 0, 16, 360),
    pygame.Rect(140, 80, 30, 200),
    pygame.Rect(300, 160, 120, 30),
]
player = pygame.Rect(60, 160, 32, 32)
speed = 4
running = True

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

    keys = pygame.key.get_pressed()
    dx = (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * speed
    dy = (keys[pygame.K_DOWN] - keys[pygame.K_UP]) * speed

    player.x += dx
    for wall in walls:
        if player.colliderect(wall):
            if dx > 0:
                player.right = wall.left
            elif dx < 0:
                player.left = wall.right

    player.y += dy
    for wall in walls:
        if player.colliderect(wall):
            if dy > 0:
                player.bottom = wall.top
            elif dy < 0:
                player.top = wall.bottom

    screen.fill((235, 230, 220))
    for wall in walls:
        pygame.draw.rect(screen, (70, 70, 90), wall)
    pygame.draw.rect(screen, (230, 90, 70), player)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Walk into the walls, then slide along them while holding two arrows: the player stops on one axis and keeps moving on the other. Platformers use the same idea, with gravity as the dy.

Circles

For round things (balls, planets, explosions) a rectangle is a poor fit at the corners. Two circles touch when the distance between their centers is less than the sum of their radii:

import pygame

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

target = pygame.Vector2(240, 180)
target_radius = 60
radius = 25
running = True

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

    mouse = pygame.Vector2(pygame.mouse.get_pos())
    hit = mouse.distance_to(target) < radius + target_radius

    screen.fill((20, 22, 36))
    pygame.draw.circle(screen, (240, 90, 90) if hit else (90, 140, 240), target, target_radius)
    pygame.draw.circle(screen, (250, 220, 120), mouse, radius, width=3)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Move the pointer over the game: the big circle turns red when the small one touches it, exactly at the curve. Sprite groups can do the same with pygame.sprite.collide_circle.

Fast objects

A bullet moving 30 pixels a frame can jump over a 10 pixel enemy between two frames, so the overlap never happens. Make fast objects longer than their speed, split the move into smaller steps, or check the line the bullet traveled with rect.clipline(start, end).