What a Pygame Rect is and why you need one
A Pygame Rect is a rectangular shape object that stores four pieces of information: the x position, y position, width, and height of a rectangle. Pygame uses Rects for two separate purposes, and this matters because it changes how you create one. First, Rects act as invisible collision boxes — they track where something is on screen so you can detect when two objects touch. Second, Rects can be drawn as visible shapes on your game window using the pygame.draw.rect() function. You need to understand the difference because you create a Rect the same way for both uses, but you only see it on screen if you explicitly draw it.
Most Pygame tutorials skip over this distinction, which is why people get confused when they create a Rect and nothing appears. The Rect object itself is just data. Drawing it requires a separate step.
Key Takeaways
- Create a Rect using pygame.Rect(x, y, width, height), where x and y are the top-left corner position in pixels.
- Draw the Rect to your screen by calling pygame.draw.rect(surface, color, rect) inside your game loop, after updating the display.
- Rect objects are useful for both collision detection and drawing, but creating one does not automatically make it visible.
- You can move a Rect by changing its x and y attributes directly, or by using built-in methods like rect.center to position it relative to other points.
- Colors in Pygame are RGB tuples: (red, green, blue) with values from 0 to 255, so white is (255, 255, 255) and black is (0, 0, 0).
Creating a Rect object with pygame.Rect()
To create a Rect, call pygame.Rect() and pass four numbers: the x position, y position, width, and height, in that order. The x and y values are measured in pixels from the top-left corner of your game window. Width and height are also in pixels.
Here is the basic syntax:
my_rect = pygame.Rect(50, 100, 200, 150)
This creates a rectangle at position (50, 100) — meaning 50 pixels from the left edge and 100 pixels from the top edge — with a width of 200 pixels and a height of 150 pixels. The Rect object is now stored in the variable my_rect, but it is not yet drawn on screen. You have only created the data structure.
You can also create a Rect from a surface (an image or a game object) by using the get_rect() method, which is common when you load a sprite. That Rect will have the same dimensions as the surface, positioned at (0, 0) by default.
Drawing the Rect to your game window
To make the Rect visible, you must call pygame.draw.rect() inside your game loop, after you have set up your display surface. The function takes three required arguments: the surface you are drawing to, the color, and the Rect object itself.
pygame.draw.rect(screen, (255, 0, 0), my_rect)
This draws my_rect as a red rectangle on the screen surface. The color is specified as an RGB tuple: (red, green, blue), where each value ranges from 0 to 255. Red is (255, 0, 0), green is (0, 255, 0), blue is (0, 0, 255), white is (255, 255, 255), and black is (0, 0, 0).
The draw call must happen inside your game loop, typically after you clear the screen but before you update the display. A minimal example looks like this:
while running: screen.fill((0, 0, 0)) pygame.draw.rect(screen, (255, 0, 0), my_rect) pygame.display.flip()
If you forget the pygame.draw.rect() call, the Rect exists in memory but you will not see it. If you call it outside the loop, it will draw once and then disappear on the next frame when the screen clears.
Moving a Rect by changing its position
Once you have created a Rect, you can move it by changing its x and y attributes directly. These represent the pixel position of the top-left corner.
my_rect.x = 100 my_rect.y = 50
You can also move a Rect by a certain number of pixels using the move() method, which returns a new Rect at the new position without changing the original:
new_rect = my_rect.move(10, 20)
This moves the Rect 10 pixels to the right and 20 pixels down. If you want to move the original Rect in place, use move_ip() (in-place):
my_rect.move_ip(10, 20)
You can also position a Rect using named attributes like center, topleft, bottomright, and midtop. These are useful when you want to place a Rect relative to another point:
my_rect.center = (400, 300) my_rect.topleft = (0, 0)
The first line moves the Rect so its center is at (400, 300). The second moves it so its top-left corner is at (0, 0).
Drawing filled and outlined rectangles
By default, pygame.draw.rect() draws a filled rectangle. If you want only the outline, add a fourth argument specifying the border width in pixels:
pygame.draw.rect(screen, (255, 0, 0), my_rect, 5)
This draws a red rectangle outline with a border 5 pixels thick. If you set the width to 0, you get a filled rectangle (the default). If you set it to 1, you get a thin outline. There is no upper limit — you can make the border as thick as you want, though it will eventually fill the entire rectangle if the width exceeds half the rectangle's smallest dimension.
You can also use pygame.draw.rect() to draw rounded corners by adding a fifth argument for the corner radius:
pygame.draw.rect(screen, (255, 0, 0), my_rect, 0, 10)
This draws a filled rectangle with 10-pixel rounded corners. The fourth argument (0) means filled; if you want an outline with rounded corners, replace 0 with your desired border width.
Common mistakes and how to avoid them
The most common mistake is creating a Rect and expecting it to appear without calling pygame.draw.rect(). Remember: creating the Rect is step one, drawing it is step two. They are separate actions.
Another frequent error is calling pygame.draw.rect() outside the game loop. Your game loop runs many times per second (typically 60 times), and each iteration clears the screen and redraws everything. If you draw the rectangle only once before the loop starts, it will disappear as soon as the loop begins and clears the screen.
A third mistake is passing the wrong surface to pygame.draw.rect(). Make sure you are drawing to the correct display surface — usually the one you created with pygame.display.set_mode(). If you pass a different surface or a None value, the function will either draw to the wrong place or raise an error.
Finally, check your RGB color values. They must be integers from 0 to 255. If you pass a value outside this range or use a string like "red" instead of a tuple, Pygame will raise an error. Use tuples: (255, 0, 0) for red, not "red".
Using Rects for collision detection alongside drawing
Rects are powerful because they serve double duty. You can draw them on screen and use them to detect collisions at the same time. For example, if you have a player Rect and an enemy Rect, you can check if they overlap using the colliderect() method:
if player_rect.colliderect(enemy_rect): print("Collision detected!")
This returns True if the two rectangles overlap and False if they do not. You can use this inside your game loop to trigger events like damage, score changes, or game over conditions. The same Rect you draw on screen is the one you use for collision checks, so you only have to update one object's position and both the drawing and collision detection stay in sync.
Other useful Rect methods include collidepoint() to check if a single point (like a mouse click) is inside the rectangle, and collidelist() to check if a Rect collides with any Rect in a list. These are all built into the Rect object, so you do not need to write collision logic yourself.
Frequently Asked Questions
What is the difference between pygame.Rect and pygame.draw.rect?
pygame.Rect() creates a Rect object that stores position and size data. pygame.draw.rect() is a function that draws a Rect object to your screen. You need both: one to create the data, one to display it. You can have a Rect without drawing it, but you cannot draw a Rect without creating one first.
Can I change the size of a Rect after I create it?
Yes. You can change the width and height attributes directly: my_rect.width = 300. You can also use the inflate() method to grow or shrink a Rect by a certain number of pixels: my_rect.inflate(50, 50) makes it 50 pixels wider and 50 pixels taller. Use inflate_ip() to change the Rect in place.
How do I draw a rectangle at the center of my screen?
Create the Rect first, then set its center to the middle of your screen. If your screen is 800 by 600 pixels, the center is at (400, 300): my_rect.center = (400, 300). Then draw it normally with pygame.draw.rect().
What happens if I draw a Rect outside the screen boundaries?
Pygame will draw it anyway, but only the part that overlaps your screen will be visible. The rest is clipped. This is useful for animations where objects move off screen — you do not have to delete them, just let them draw off the edge.
Can I draw multiple rectangles in one frame?
Yes. Call pygame.draw.rect() as many times as you need inside your game loop, once for each rectangle. Draw them in the order you want them to appear, because later draws appear on top of earlier ones.