Pygame Documentation and Tutorial with Examples
A free pygame reference for Python game making: the game loop, drawing, Rect, Surface and blit, keyboard and mouse input, images, sprites, collisions, text, sound and animation. Every example is a small game you can edit and play on the page, on the real pygame-ce.
Start the courseGetting Started
- What Is PygamePygame is a free Python library for making 2D games: it opens a window, draws shapes and images, reads the keyboard and mouse, and plays sound. Here is what it does, what it is good for, and a small game you can play on this page.
- Install PygameInstall pygame with one pip command on Windows, macOS or Linux, check that it works, and fix the errors people hit most: pip not found, No module named pygame, and the wrong Python.
- Pygame vs pygame-cepygame-ce is the community edition of pygame, a fork made by most of pygame's active developers. Both are imported as pygame and run the same code. Here is how they differ and which to install.
- First ProgramA pygame tutorial for your first program: import pygame, open a window with set_mode, keep it open with a loop, draw into it and close it cleanly. Every line explained.
The Game Loop
- Game LoopEvery pygame game is one loop that runs about sixty times a second: handle events, update the game, draw the frame. Learn the three steps, why their order matters, and how to organize a bigger game around them.
- Clock and FPSpygame.time.Clock keeps a game at a steady speed. Learn what clock.tick(60) does, how to read the frame rate with get_fps(), and how delta time makes movement the same speed on fast and slow computers.
Drawing
- ColorsPygame colors are (red, green, blue) numbers from 0 to 255, color names such as "tomato", or hex strings. Learn all three, pygame.Color, transparency with alpha, and the error you get from a bad color.
- pygame.drawpygame.draw draws shapes on any Surface: rect, circle, line, lines, polygon, ellipse and arc. See every function's arguments, outlines with width, rounded corners with border_radius, and a scene built from shapes.
- Rectpygame.Rect stores a rectangle's position and size. It moves objects, places them by their center or edges, keeps them on screen and checks collisions. Here are its attributes, methods and the float trap.
- SurfaceA Surface is an image in memory: the screen is one, every loaded image is one, and you can make your own. Learn pygame.Surface, fill, SRCALPHA, set_alpha, set_colorkey, subsurface and convert.
- blit()blit() copies one Surface onto another: an image onto the screen, text onto a panel, a tile onto a map. Learn the destination argument, blitting at a Rect, the area argument for sprite sheets, and blits() for many at once.
Events and Input
- EventsPygame reports everything the player does as events: QUIT, KEYDOWN, KEYUP, MOUSEBUTTONDOWN, MOUSEMOTION and more. Learn the event loop, the attributes of each event type, and your own custom events.
- Keyboard InputRead the keyboard in pygame two ways: KEYDOWN events for single presses such as jumping, and pygame.key.get_pressed() for keys held down such as walking. With key constants, WASD and arrow keys, modifiers and typed text.
- Mouse InputRead the mouse in pygame: MOUSEBUTTONDOWN and MOUSEBUTTONUP events for clicks, pygame.mouse.get_pos() and get_pressed() for its state, clickable buttons with collidepoint, and dragging objects.
Images and Sprites
- Loading ImagesLoad PNG and JPG images with pygame.image.load(), keep their transparency with convert_alpha(), place them with get_rect(), draw a tiled background, and fix the file not found error.
- Scale, Rotate, Flippygame.transform resizes, rotates and mirrors Surfaces. Learn scale, scale_by, smoothscale, rotate, rotozoom and flip, how to rotate an image around its center, and why you should always transform the original.
- Sprites and Groupspygame.sprite.Sprite bundles an image, a Rect and an update() method into one game object, and pygame.sprite.Group updates and draws many of them in one line. Learn both, kill(), and how to structure a game with sprites.
Collisions
- Collision DetectionDetect collisions in pygame with Rect methods: colliderect for two boxes, collidepoint for clicks, collidelist for many, plus circle collisions by distance and how to stop a player at a wall instead of passing through.
- Sprite CollisionsCheck collisions between sprites and groups: spritecollide for one sprite against a group, groupcollide for two groups, dokill to remove what was hit, and pixel-perfect collisions with masks.
Text and Fonts
- TextDraw text in pygame: make a Font, render() the text into a Surface, then blit it. Learn centering, a live score, text with a background, several lines, and why text should be rendered only when it changes.
- FontsChoose fonts in pygame: the built-in default font, system fonts with SysFont and the list from get_fonts(), your own .ttf files with pygame.font.Font, and bold, italic and underline.
Time and Animation
- TimersMake things happen on a schedule in pygame: pygame.time.set_timer() posts an event every few milliseconds, pygame.time.get_ticks() measures time for cooldowns and countdowns, and why time.sleep() freezes a game.
- AnimationAnimate characters in pygame: swap between frames on a timer, cut frames out of a sprite sheet with subsurface, play a different animation when walking, and run one-off effects such as explosions.
- Vector2pygame.Vector2 stores an x and a y and does the math games need: add velocities, normalize so diagonals are not faster, aim at a target, rotate, measure distances and move toward a point.
Comparisons
- Pygame Zero vs PygamePygame Zero is a beginner layer on top of pygame: no game loop to write, just draw() and update() functions and Actors. Here is the same game in both, what each hides or shows, and when to move from one to the other.
- Pygame vs GodotPygame is a Python library where your code is the whole game; Godot is a free engine with an editor, scenes and its own Python-like language. Compare how each works, what each is good at, and which to learn first.
- Pygame vs Arcade vs PygletThree Python game libraries compared: pygame, the oldest and most used, built on SDL; Arcade, a modern sprite and physics library on OpenGL; and pyglet, a lower-level windowing and multimedia library. Code, strengths and which to choose.
