HOWTO · Pygame
Detectar colisiones en Pygame
Este tutorial analiza y presenta los diferentes métodos que podemos usar para probar o detectar colisiones en Pygame.
En esta página
La detección de colisiones en Pygame depende de las formas y del resultado que necesites. Usa collidepoint() para comprobar una posición frente a un rectángulo, colliderect() para comparar dos rectángulos y collidelist() o collidedict() para buscar en colecciones. Para círculos, compara la distancia entre sus centros con la suma de sus radios. Para sprites irregulares, combina una comprobación preliminar de rectángulos con la superposición de máscaras. Los ejemplos siguientes explican el comportamiento pertinente de la API; no son bucles de juego completos. (collidelistall(); collidedictall(); pygame.mask.from_surface())
Elegir una comprobación de colisión según la tarea
Empieza por la comprobación menos costosa que se ajuste al juego. Los rectángulos son rápidos y suelen bastar para plataformas, paredes y áreas de impacto. Una comprobación de punto sirve para seleccionar con el ratón. Los métodos para listas y diccionarios buscan entre varios rectángulos y devuelven posiciones o claves útiles. El cálculo de círculos es adecuado para objetos redondos. Las máscaras comprueban los píxeles opacos y ofrecen más precisión, pero requieren más cálculo.
pygame.Rect almacena la posición y el tamaño de un rectángulo. Los métodos de colisión de Pygame indican una superposición geométrica; no mueven los objetos ni resuelven la colisión. Usa el resultado para decidir qué debe hacer el juego, por ejemplo, detener el movimiento, recoger un objeto o activar un botón.
Comprobar si un punto está dentro de un rectángulo
Llama a rect.collidepoint(x, y) o pasa las coordenadas juntas como un par con rect.collidepoint((x, y)). El método devuelve True cuando el punto está dentro del rectángulo y False en caso contrario. Esto resulta útil para comprobar si el cursor está sobre un botón: pasa la posición actual del ratón y cambia el aspecto del botón cuando el resultado sea verdadero. Un punto situado en el borde derecho o inferior queda fuera, porque la geometría de colisión de Rect excluye esos bordes.
Comprobar si dos rectángulos se superponen
Crea dos objetos pygame.Rect y llama a first.colliderect(second). El método devuelve un booleano, así que puedes usarlo directamente en una instrucción if. Por ejemplo, player_rect.colliderect(wall_rect) permite determinar si el área de impacto del jugador se cruza con una pared. Los rectángulos que solo se tocan por un borde no se superponen. Esta comprobación es rápida, pero un área de impacto rectangular puede abarcar partes transparentes del sprite.
Buscar colisiones en una lista de rectángulos
Para comparar un rectángulo con una secuencia de rectángulos, usa collidelist(rectangles) para obtener el índice de la primera coincidencia. Si no hay ninguna, devuelve -1. Usa collidelistall(rectangles) cuando necesites todos los índices coincidentes; devuelve una lista de índices, que puede estar vacía si no hay superposición. Los índices corresponden a la secuencia original, así que puedes usarlos para recuperar el objeto del juego o el rectángulo asociado. Consulta la documentación oficial de Rect de Pygame para conocer estos métodos y otros comportamientos de colisión relacionados.
Por ejemplo, si player = pygame.Rect(10, 10, 20, 20) y los rectángulos de los índices 1 y 2 de una lista se superponen con él, player.collidelist(walls) devuelve 1, mientras que player.collidelistall(walls) devuelve [1, 2]. Estos ejemplos de llamadas a la API aparecen en línea porque importar Pygame en el entorno de ejecución configurado genera una advertencia específica de la plataforma; las llamadas y sus resultados se basan en la semántica documentada de la API y no en una comprobación durante la ejecución. La diferencia permite detenerse al encontrar cualquier impacto o revisar cada pared que se cruza. Los métodos devuelven posiciones de la lista original, no objetos sprite.
Buscar colisiones en un diccionario de rectángulos
Usa collidedict(rect_dict, use_values=True) para obtener un par con una clave coincidente y su rectángulo, o None si no hay ninguno. El argumento use_values=True es necesario cuando el diccionario almacena rectángulos como valores; sin él, el método busca en las claves valores similares a rectángulos y genera TypeError si las claves son cadenas corrientes. Usa collidedictall(rect_dict, use_values=True) para obtener todos los pares coincidentes de clave y rectángulo. Esto resulta práctico cuando las claves identifican objetos del juego, por ejemplo, {"door": door_rect, "crate": crate_rect}. La documentación oficial de Rect de Pygame describe ambos métodos para diccionarios.
Por ejemplo, si el rectángulo del jugador se superpone con los valores correspondientes a "crate" y "door", player.collidedict(rectangles, use_values=True) devuelve un par coincidente de clave y rectángulo, mientras que player.collidedictall(rectangles, use_values=True) devuelve ambos pares. Estas llamadas a la API aparecen en línea porque importar Pygame en el entorno de ejecución configurado genera una advertencia específica de la plataforma; sus resultados describen el comportamiento documentado de la API y no se han verificado aquí durante la ejecución. El método de una sola coincidencia sirve cuando basta con detectar cualquier impacto; usa la variante de todas las coincidencias si el juego debe gestionar cada superposición. La clave devuelta permite relacionar el rectángulo alcanzado con su objeto, pero no determina cómo resolver la colisión.
Comprobar si dos círculos se superponen
Pygame no proporciona un método collidecircle() para Rect. Para dos círculos con centros (x1, y1) y (x2, y2) y radios r1 y r2, calcula la distancia entre sus centros y compárala con la suma de sus radios. Los círculos se tocan o se superponen cuando la distancia es menor o igual que r1 + r2. Para obtener un resultado booleano, compara los valores al cuadrado y evita calcular la raíz cuadrada:
(x1 - x2) ** 2 + (y1 - y2) ** 2 <= (r1 + r2) ** 2
Mantén cada centro y radio sincronizados con la posición del objeto. Este cálculo supone áreas de impacto circulares; no es una comprobación precisa para un sprite que no sea circular.
Comprobar la superposición píxel a píxel con máscaras
Si las áreas de impacto rectangulares son demasiado imprecisas para sprites transparentes o de formas irregulares, crea máscaras a partir de las superficies con pygame.mask.from_surface(surface). Primero usa colliderect() como comprobación preliminar; crea o consulta las máscaras solo cuando los rectángulos se superpongan. Después llama a first_mask.overlap(second_mask, offset). El desplazamiento indica la posición de la segunda máscara respecto a la primera; suele ser (second_rect.x - first_rect.x, second_rect.y - first_rect.y). Mask.overlap() devuelve un punto si se superpone algún píxel opaco, o None si no se superpone ningún píxel de las máscaras. Consulta la documentación oficial de máscaras de Pygame para obtener detalles sobre su creación y la superposición.
Las máscaras requieren más trabajo que las comprobaciones de rectángulos, así que úsalas solo cuando la precisión adicional mejore el juego. Guarda en caché las máscaras de superficies que no cambian, en vez de volver a crearlas en cada fotograma. El método comprueba los píxeles de la máscara, no efectos visuales como sombras o resplandores, salvo que esos píxeles formen parte de la superficie de origen.
Una pequeña ilustración geométrica independiente puede mostrar cómo se decide la superposición de rectángulos sin necesitar una ventana de Pygame ni recursos de imagen. Es lógica de Python sin dependencias, no una prueba de la API de Pygame.
El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.
first = (100, 100, 50, 50)
second = (120, 120, 50, 50)
def overlaps(a, b):
ax, ay, aw, ah = a
bx, by, bw, bh = b
return ax < bx + bw and bx < ax + aw and ay < by + bh and by < ay + ah
print(overlaps(first, second))
True