Pygame Sprite Collisions: spritecollide and Masks

Once your objects are sprites in groups, one function call checks a sprite against a whole group. This game has a ship that shoots lasers at a row of enemies:

import pygame

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

ship_image = pygame.image.load("assets/images/ship.png").convert_alpha()
enemy_image = pygame.image.load("assets/images/enemy_red.png").convert_alpha()
laser_image = pygame.image.load("assets/images/laser.png").convert_alpha()


class Ship(pygame.sprite.Sprite):
    def __init__(self):
        super().__init__()
        self.image = ship_image
        self.rect = self.image.get_rect(midbottom=(240, 350))

    def update(self):
        keys = pygame.key.get_pressed()
        self.rect.x += (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * 6
        self.rect.clamp_ip(screen.get_rect())


class Enemy(pygame.sprite.Sprite):
    def __init__(self, x, y):
        super().__init__()
        self.image = enemy_image
        self.rect = self.image.get_rect(center=(x, y))


class Laser(pygame.sprite.Sprite):
    def __init__(self, pos):
        super().__init__()
        self.image = laser_image
        self.rect = self.image.get_rect(midbottom=pos)

    def update(self):
        self.rect.y -= 9
        if self.rect.bottom < 0:
            self.kill()


ship = pygame.sprite.GroupSingle(Ship())
enemies = pygame.sprite.Group(Enemy(60 + i * 90, 70) for i in range(5))
lasers = pygame.sprite.Group()
score = 0
running = True

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE:
            lasers.add(Laser(ship.sprite.rect.midtop))

    ship.update()
    lasers.update()

    hits = pygame.sprite.groupcollide(lasers, enemies, True, True)
    score += len(hits)
    if not enemies:
        enemies.add(Enemy(60 + i * 90, 70) for i in range(5))

    screen.fill((8, 10, 26))
    enemies.draw(screen)
    lasers.draw(screen)
    ship.draw(screen)
    screen.blit(font.render(f"Score: {score}", True, "white"), (10, 330))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Press Play, click the game, move with the arrow keys and shoot with Space. groupcollide(lasers, enemies, True, True) finds every laser touching an enemy and removes both.

The collision functions

dokill=True removes the sprites that collided from all their groups, which is what you want for coins and bullets. Use False when the sprite should stay, such as a wall or the player.

Every collide function takes an optional last argument, collided, which picks the test:

pygame.sprite.spritecollide(player, enemies, False, pygame.sprite.collide_circle)

Pixel-perfect collisions with masks

Rect collisions count the transparent corners of an image, so a round enemy "hits" before it visibly touches. A mask records which pixels of an image are solid, and collide_mask compares those:

import pygame

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


class Thing(pygame.sprite.Sprite):
    def __init__(self, path, center):
        super().__init__()
        self.image = pygame.transform.scale_by(pygame.image.load(path).convert_alpha(), 2)
        self.rect = self.image.get_rect(center=center)
        self.mask = pygame.mask.from_surface(self.image)


ghost = Thing("assets/images/ghost.png", (240, 180))
ball = Thing("assets/images/spike_ball.png", (100, 180))
ghosts = pygame.sprite.Group(ghost)
running = True

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

    keys = pygame.key.get_pressed()
    ball.rect.x += (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * 3
    ball.rect.y += (keys[pygame.K_DOWN] - keys[pygame.K_UP]) * 3

    by_rect = pygame.sprite.spritecollide(ball, ghosts, False)
    by_mask = pygame.sprite.spritecollide(ball, ghosts, False, pygame.sprite.collide_mask)

    screen.fill((200, 60, 60) if by_mask else (40, 40, 60))
    pygame.draw.rect(screen, (255, 220, 0) if by_rect else (90, 90, 110), ghost.rect, width=1)
    pygame.draw.rect(screen, (255, 220, 0) if by_rect else (90, 90, 110), ball.rect, width=1)
    screen.blit(ghost.image, ghost.rect)
    screen.blit(ball.image, ball.rect)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Move the spike ball toward the ghost with the arrow keys. The outlines turn yellow as soon as the rectangles overlap; the background turns red only when real pixels touch.

Set self.mask once in __init__: collide_mask uses it if it exists, and otherwise builds a new mask on every check, which is slow. Rebuild it only when the image changes. Masks cost more than rects, so a common pattern is a cheap spritecollideany first, then the mask test only on the sprites it found.