Pygame Cheat Sheet: guia rápido
Última atualização
Configuração e loop do jogo
Todo programa pygame abre uma janela e depois repete um loop até o jogador sair.
| Operação | Código |
|---|---|
| Instalar o pygame-ce | python3 -m pip install pygame-ce |
| Importar e iniciar o pygame | import pygame
pygame.init() |
| Abrir uma janela | screen = pygame.display.set_mode((640, 480)) |
| Definir o título da janela | pygame.display.set_caption("My Game") |
| Criar um relógio | clock = pygame.time.Clock() |
| O loop do jogo | running = True
while running:
for event in pygame.event.get():
if event.type == pygame.QUIT:
running = False
screen.fill("black")
pygame.display.flip()
clock.tick(60) |
| Encerrar depois do loop | pygame.quit() |
Tela
A tela é uma Surface; nada aparece até você chamar flip.
| Operação | Código |
|---|---|
| Mostrar o quadro pronto | pygame.display.flip() |
| Mostrar só algumas áreas | pygame.display.update([rect1, rect2]) |
| Limpar a tela | screen.fill((30, 30, 46)) |
| Tamanho da janela | screen.get_size(), screen.get_width() |
| A tela como Rect | screen.get_rect() |
| Janela redimensionável | pygame.display.set_mode((640, 480), pygame.RESIZABLE) |
| Tela cheia no tamanho da área de trabalho | pygame.display.set_mode((0, 0), pygame.FULLSCREEN) |
Cores e desenho
As funções de pygame.draw recebem uma superfície, uma cor e uma posição. width=0 preenche.
| Operação | Código |
|---|---|
| Cor em RGB | (255, 140, 0) |
| Cor por nome ou hexadecimal | "tomato", "#ff8c00", pygame.Color("gold") |
| Retângulo | pygame.draw.rect(screen, "red", (x, y, w, h)) |
| Contorno e cantos arredondados | pygame.draw.rect(screen, "red", rect, width=2, border_radius=8) |
| Círculo (pelo centro) | pygame.draw.circle(screen, "blue", (cx, cy), radius) |
| Linha | pygame.draw.line(screen, "white", (x1, y1), (x2, y2), 3) |
| Polígono | pygame.draw.polygon(screen, "green", [(0, 0), (40, 0), (20, 30)]) |
| Elipse dentro de uma caixa | pygame.draw.ellipse(screen, "purple", (x, y, w, h)) |
Rect
Um Rect guarda uma posição e um tamanho como números inteiros.
| Operação | Código |
|---|---|
| Criar um Rect | player = pygame.Rect(x, y, width, height) |
| Posicionar por qualquer ponto | player.center = (320, 240), player.bottom = 400 |
| Bordas e cantos | left, right, top, bottom, topleft, midbottom |
| Mover no lugar | player.move_ip(dx, dy) |
| Cópia movida | moved = player.move(dx, dy) |
| Manter dentro da tela | player.clamp_ip(screen.get_rect()) |
| Aumentar em volta do centro | bigger = player.inflate(20, 20) |
| Posições com casas decimais (pygame-ce) | pygame.FRect(10.5, 20.25, 40, 40) |
Imagens, Surfaces e blit
Carregue as imagens uma vez, antes do loop, e faça blit delas a cada quadro.
| Operação | Código |
|---|---|
| Carregar uma imagem com transparência | img = pygame.image.load("player.png").convert_alpha() |
| Carregar uma imagem opaca | bg = pygame.image.load("sky.png").convert() |
| Desenhar uma imagem | screen.blit(img, (x, y)) |
| Desenhar centralizada | screen.blit(img, img.get_rect(center=(320, 240))) |
| Nova Surface em branco | panel = pygame.Surface((200, 100)) |
| Surface transparente | layer = pygame.Surface((200, 100), pygame.SRCALPHA) |
| Deixar uma Surface inteira translúcida | img.set_alpha(128) |
| Recortar um quadro de uma sprite sheet | frame = sheet.subsurface((0, 0, 32, 32)) |
| Salvar uma captura de tela | pygame.image.save(screen, "shot.png") |
Transformações
Cada função retorna uma Surface nova; transforme o original, não o último resultado.
| Operação | Código |
|---|---|
| Redimensionar | pygame.transform.scale(img, (64, 64)) |
| Escalar por um fator | pygame.transform.scale_by(img, 2) |
| Redimensionar com suavização | pygame.transform.smoothscale(img, (64, 64)) |
| Girar (sentido anti-horário, em graus) | pygame.transform.rotate(img, 45) |
| Girar em torno do centro | rotated = pygame.transform.rotate(original, angle)
rect = rotated.get_rect(center=rect.center) |
| Espelhar na horizontal | pygame.transform.flip(img, True, False) |
Eventos e teclado
Use eventos para toques únicos e get_pressed() para teclas seguradas.
| Operação | Código |
|---|---|
| Ler os eventos deste quadro | for event in pygame.event.get(): |
| Janela fechada | event.type == pygame.QUIT |
| Uma tecla foi pressionada | event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE |
| Uma tecla foi solta | event.type == pygame.KEYUP |
| Caractere digitado | event.unicode |
| Teclas seguradas agora | keys = pygame.key.get_pressed()
if keys[pygame.K_LEFT]:
x -= 5 |
| Direção a partir de duas teclas | dx = keys[pygame.K_RIGHT] - keys[pygame.K_LEFT] |
| Teclas pressionadas neste quadro (pygame-ce) | pygame.key.get_just_pressed()[pygame.K_SPACE] |
| Constantes de teclas | K_a...K_z, K_0...K_9, K_UP, K_RETURN, K_ESCAPE, K_LSHIFT |
| Nome de uma tecla | pygame.key.name(event.key) |
| Evento personalizado | HIT = pygame.event.custom_type()
pygame.event.post(pygame.event.Event(HIT)) |
Mouse
Botões: 1 esquerdo, 2 do meio, 3 direito.
| Operação | Código |
|---|---|
| Um botão foi pressionado | event.type == pygame.MOUSEBUTTONDOWN and event.button == 1 |
| Onde foi pressionado | event.pos |
| Posição atual do ponteiro | x, y = pygame.mouse.get_pos() |
| Botões segurados agora | left, middle, right = pygame.mouse.get_pressed() |
| O mouse se moveu | event.type == pygame.MOUSEMOTION, event.rel |
| A roda girou | event.type == pygame.MOUSEWHEEL, event.y |
| Clique dentro de um botão | button_rect.collidepoint(event.pos) |
| Esconder o ponteiro | pygame.mouse.set_visible(False) |
Sprites e grupos
Um sprite guarda uma image e um rect; um grupo atualiza e desenha vários.
| Operação | Código |
|---|---|
| Classe de sprite | class Coin(pygame.sprite.Sprite):
def __init__(self, pos):
super().__init__()
self.image = coin_img
self.rect = self.image.get_rect(center=pos) |
| Criar um grupo | coins = pygame.sprite.Group() |
| Adicionar a um grupo | coins.add(Coin((100, 50))) |
| Atualizar todos os sprites | coins.update() |
| Desenhar todos os sprites | coins.draw(screen) |
| Tirar um sprite de todos os grupos | coin.kill() |
| Grupo com um único sprite | player = pygame.sprite.GroupSingle(Player()) |
Colisões
Rects colidem quando se sobrepõem; bordas que só se encostam não contam.
| Operação | Código |
|---|---|
| Dois retângulos | a.colliderect(b) |
| Ponto dentro | rect.collidepoint(x, y) |
| O primeiro de vários | rect.collidelist(walls) # index or -1 |
| Sprite contra um grupo | hits = pygame.sprite.spritecollide(player, coins, True) |
| Qualquer colisão | pygame.sprite.spritecollideany(player, enemies) |
| Grupo contra grupo | pygame.sprite.groupcollide(bullets, enemies, True, True) |
| Pixel a pixel | pygame.sprite.spritecollide(a, group, False, pygame.sprite.collide_mask) |
| Círculos | pygame.Vector2(a).distance_to(b) < r1 + r2 |
Texto e fontes
Renderize o texto em uma Surface e depois faça blit.
| Operação | Código |
|---|---|
| Fonte padrão | font = pygame.font.Font(None, 36) |
| Fonte do sistema | font = pygame.font.SysFont("arial", 24) |
| Arquivo de fonte | font = pygame.font.Font("pixel.ttf", 32) |
| Renderizar texto | text = font.render("Score: 10", True, "white") |
| Desenhar centralizado | screen.blit(text, text.get_rect(center=(320, 40))) |
| Quebrar texto longo (pygame-ce) | font.render(story, True, "white", None, 400) |
| Tamanho sem renderizar | font.size("Hello") |
| Fontes instaladas | pygame.font.get_fonts() |
Som e música
Carregue os sons uma vez. A música toca uma faixa em streaming direto do arquivo.
| Operação | Código |
|---|---|
| Carregar um som | jump = pygame.mixer.Sound("jump.ogg") |
| Tocar o som | jump.play() |
| Volume do som | jump.set_volume(0.5) |
| Carregar música | pygame.mixer.music.load("theme.ogg") |
| Repetir a música sem parar | pygame.mixer.music.play(-1) |
| Pausar e retomar | pygame.mixer.music.pause(), pygame.mixer.music.unpause() |
| Parar a música | pygame.mixer.music.stop() |
Tempo e timers
Os ticks são em milissegundos.
| Operação | Código |
|---|---|
| Limitar a taxa de quadros | clock.tick(60) |
| Delta time em segundos | dt = clock.tick(60) / 1000 |
| Taxa de quadros atual | clock.get_fps() |
| Milissegundos desde o init | pygame.time.get_ticks() |
| Evento de timer repetido | SPAWN = pygame.event.custom_type()
pygame.time.set_timer(SPAWN, 1000) |
| Timer de uma vez só | pygame.time.set_timer(SPAWN, 2000, loops=1) |
| Parar um timer | pygame.time.set_timer(SPAWN, 0) |
Vector2
Números decimais para posições e velocidades.
| Operação | Código |
|---|---|
| Criar um vetor | pos = pygame.Vector2(100, 200) |
| Mover por uma velocidade | pos += velocity * dt |
| Comprimento | velocity.length() |
| Mesma velocidade nas diagonais | if direction.length() > 0:
direction = direction.normalize() |
| Distância entre pontos | pos.distance_to(target) |
| Girar | velocity.rotate(90) |
| Avançar até um ponto (pygame-ce) | pos.move_towards_ip(target, 5) |
O código de pygame que você usa ao criar um jogo 2D em Python, agrupado por tarefa: o loop do jogo, a tela, cores e desenho, Rect, imagens e blit, escala e rotação, entrada de teclado e mouse, sprites e grupos, colisões, texto, som, timers e Vector2. Cada linha é um trecho curto para colar, ao lado do que ele faz.
Tudo aqui foi escrito para o pygame-ce 2.5, a edição da comunidade do pygame, que continua sendo importada com import pygame. As linhas marcadas com pygame-ce usam os recursos dele; todas as outras também funcionam no pygame original. Teste qualquer trecho no playground de pygame, que roda pygame no seu navegador sem instalar nada. Ainda não sabe Python? Comece pelo cheat sheet de Python.
Perguntas frequentes sobre o cheat sheet de pygame
Este cheat sheet de pygame é grátis?
Sim. É grátis e não precisa de cadastro. Salve nos favoritos, ou imprima em PDF pelo navegador, e volte sempre que precisar da chamada exata para um grupo de sprites, um som ou um teste de colisão.
Este cheat sheet funciona com pygame e pygame-ce?
Sim. Os dois são importados com
import pygame e compartilham quase toda a API. As linhas marcadas com pygame-ce (FRect, scale_by, get_just_pressed, a quebra de texto e move_towards_ip) precisam do pygame-ce, e todo o resto roda em qualquer um dos dois.Por que minha janela do pygame não responde?
O loop do jogo não está lendo os eventos. Chame
pygame.event.get() uma vez a cada quadro, mesmo que ignore os eventos, e termine cada quadro com pygame.display.flip() e clock.tick(60).Devo usar eventos ou key.get_pressed() para a entrada?
Use um evento
KEYDOWN para ações que acontecem uma vez por toque, como pular ou abrir um menu. Use pygame.key.get_pressed() para ações que duram enquanto a tecla está segurada, como andar.Recursos relacionados
Mais folhas de consulta
