Collision Detection — colliderect

By the end of this lesson you can:

• Explain what actor_a.colliderect(actor_b) checks and when it returns True.
• Use Rect((x, y), (w, h)).colliderect(other_rect) to test two plain rectangles.
• Run a script where two coloured boxes change to red the moment their bounding rectangles overlap.

You used colliderect in PZ-18 to catch the mouse. Before writing more code, make sure the idea is clear. Two rectangles overlap when neither is completely to the left, right, above, or below the other. Try this logic:

# Two rectangles as (x, y, width, height)
ax, ay, aw, ah = 100, 100, 80, 60
bx, by, bw, bh = 150, 120, 80, 60

# They overlap if none of the four "no overlap" cases is true:
no_overlap = (ax + aw <= bx) or (bx + bw <= ax) or (ay + ah <= by) or (by + bh <= ay)
print("overlap:", not no_overlap)

overlap: True

Think of each actor or Rect as a cardboard cutout lying on a table. colliderect asks: do these two cardboard rectangles touch or overlap right now? It returns True if they do, False if there is any gap.

With two Actors

def update():
    if player.colliderect(enemy):
        print("Hit!")   # called every frame they overlap

The bounding box of each Actor is calculated from the image size and .pos. You never set the box manually.

With two Rects

Rect is Pygame Zero's plain rectangle object. Create one with Rect((x, y), (width, height)):

box_a = Rect((100, 100), (80, 60))
box_b = Rect((150, 120), (80, 60))

if box_a.colliderect(box_b):
    print("boxes overlap")

Rect attributes you can read and set

r = Rect((200, 150), (60, 40))
print(r.x, r.y)         # top-left corner
print(r.right, r.bottom) # opposite corner
print(r.center)          # centre point as (x, y) tuple
print(r.width, r.height)

Why it matters

colliderect runs at native speed. Checking a hundred pairs per frame is still instant. It is the foundation of platformer ground checks, bullet hits, item pickups, and push-back walls.

The story

Arjun wants to understand exactly when collision fires. He builds a minimal scene: one box he can move with arrow keys, one stationary box. Both turn red the moment their rectangles overlap. Save as collide_demo.py:

# collide_demo.py — part 1: setup
import pgzrun

WIDTH = 600
HEIGHT = 400
TITLE = "colliderect Demo"
SPEED = 3

# Moving box — tracked as a Rect
mover = Rect((50, 180), (60, 60))

# Static box in the middle
wall = Rect((260, 160), (80, 80))

# collide_demo.py — part 2: draw and update
def draw():
    screen.fill("white")
    touching = mover.colliderect(wall)
    mover_col = "red" if touching else "dodgerblue"
    wall_col = "red" if touching else "darkorange"
    screen.draw.filled_rect(mover, mover_col)
    screen.draw.filled_rect(wall, wall_col)
    screen.draw.rect(mover, "black")
    screen.draw.rect(wall, "black")
    status = "TOUCHING" if touching else "separate"
    screen.draw.text(
        f"Status: {status}",
        topleft=(10, 10), fontsize=26, color="black",
    )
    screen.draw.text(
        "Arrow keys to move blue box",
        topleft=(10, 370), fontsize=18, color="grey",
    )

def update():
    if keyboard.right:
        mover.x += SPEED
    if keyboard.left:
        mover.x -= SPEED
    if keyboard.up:
        mover.y -= SPEED
    if keyboard.down:
        mover.y += SPEED

pgzrun.go()

What you'll see

colliderect returns True when two rectangles share any overlapping area this frame. It works between two Actors, two Rects, or an Actor and a Rect. Rect((x, y), (w, h)) is a plain rectangle with handy attributes like .center, .right, and .bottom. Use or to check multiple objects at once.