HOWTO · Pygame

파이게임에서 충돌 감지

이 튜토리얼에서는 Pygame에서 충돌 테스트 또는 탐지에 사용할 수 있는 다양한 방법에 대해 논의하고 소개합니다.

이 페이지의 내용

Pygame에서 충돌을 감지하는 방법은 확인하려는 도형과 필요한 결과에 따라 달라집니다. 위치와 사각형의 충돌은 collidepoint()로, 두 사각형의 겹침은 colliderect()로 확인하고, 컬렉션 검색에는 collidelist()나 collidedict()를 사용합니다. 원끼리의 충돌은 중심 사이의 거리와 반지름을 비교하면 됩니다. 불규칙한 스프라이트에는 사각형으로 먼저 확인한 뒤 마스크로 겹치는 픽셀을 검사할 수 있습니다. 아래 예제는 관련 API의 동작을 설명하며, 완전한 게임 루프는 아닙니다. (함께 알아둘 메서드: collidelistall(); collidedictall(); pygame.mask.from_surface())

작업에 맞는 충돌 검사 선택하기

게임플레이에 맞는 검사 중 계산 비용이 가장 낮은 방법부터 선택하세요. 사각형 검사는 빠르며 플랫폼, 벽, 히트박스에 흔히 충분합니다. 마우스로 대상을 선택할 때는 점 검사를 사용할 수 있습니다. 리스트와 딕셔너리 메서드는 여러 사각형을 검색해 인덱스나 키를 반환합니다. 둥근 물체에는 원의 기하 계산이 적합합니다. 마스크는 불투명한 픽셀을 검사하므로 더 정밀하지만 계산 비용이 더 큽니다.

pygame.Rect는 사각형의 위치와 크기를 저장합니다. Pygame의 충돌 메서드는 기하학적으로 겹치는지만 알려 줍니다. 물체를 이동시키거나 충돌을 해결하지는 않습니다. 이 결과를 바탕으로 이동을 멈추거나 아이템을 획득하거나 버튼을 여는 등 게임에서 취할 동작을 결정하세요.

점이 사각형 안에 있는지 확인하기

rect.collidepoint(x, y)를 호출하거나 좌표를 한 쌍으로 묶어 rect.collidepoint((x, y))처럼 전달하세요. 점이 사각형 안에 있으면 True, 그렇지 않으면 False를 반환합니다. 마우스 포인터가 버튼 위에 있는지 확인할 때 유용합니다. 현재 마우스 위치를 전달하고 결과가 참이면 버튼의 모양을 바꾸면 됩니다. Rect의 충돌 기하에서는 오른쪽과 아래쪽 경계를 포함하지 않으므로, 점이 그 경계에 있으면 사각형 바깥으로 판정됩니다.

두 사각형이 겹치는지 확인하기

pygame.Rect 객체 두 개를 만들고 first.colliderect(second)를 호출하세요. 불리언 값을 반환하므로 if 문에서 바로 사용할 수 있습니다. 예를 들어 player_rect.colliderect(wall_rect)로 플레이어의 히트박스가 벽과 교차하는지 확인할 수 있습니다. 두 사각형이 경계만 맞닿아 있으면 겹치는 것으로 판정되지 않습니다. 이 검사는 빠르지만, 직사각형 히트박스에는 스프라이트의 투명한 부분이 포함될 수도 있습니다.

사각형 리스트에서 충돌 찾기

사각형 하나를 사각형 시퀀스와 비교하려면 collidelist(rectangles)를 사용해 첫 번째 일치 항목의 인덱스를 얻으세요. 일치 항목이 없으면 -1을 반환합니다. 일치하는 모든 항목의 인덱스가 필요하면 collidelistall(rectangles)을 사용하세요. 겹치는 항목이 없을 때는 빈 리스트일 수 있는 인덱스 목록을 반환합니다. 인덱스는 원래 시퀀스의 위치를 가리키므로, 이를 사용해 해당 게임 객체나 사각형을 찾을 수 있습니다. 이 메서드와 관련 충돌 동작은 공식 Pygame Rect 문서를 참고하세요.

예를 들어 player = pygame.Rect(10, 10, 20, 20)이고 리스트의 인덱스 1과 2에 있는 사각형이 플레이어와 겹친다면, player.collidelist(walls)은 1을 반환하고 player.collidelistall(walls)은 [1, 2]를 반환합니다. 설정된 런타임에서 Pygame을 가져오면 플랫폼별 경고가 발생하므로, 여기서는 API 호출을 인라인 예제로 제시합니다. 호출과 반환값은 문서에 설명된 API 동작을 바탕으로 한 것이며 런타임에서 확인한 결과는 아닙니다. 첫 번째 메서드는 충돌이 하나라도 있으면 멈출 때, 두 번째 메서드는 겹치는 벽을 모두 살펴볼 때 유용합니다. 두 메서드가 반환하는 것은 원래 리스트의 인덱스이며 스프라이트 객체 자체가 아닙니다.

사각형 딕셔너리에서 충돌 찾기

일치하는 키와 사각형 쌍 하나를 얻으려면 collidedict(rect_dict, use_values=True)를 사용하세요. 일치하는 사각형이 없으면 None을 반환합니다. 딕셔너리의 값에 사각형이 저장되어 있다면 use_values=True 인수가 필요합니다. 이 인수를 생략하면 메서드는 키에서 사각형처럼 보이는 값을 찾으므로, 일반 문자열 키를 사용하면 TypeError가 발생합니다. 일치하는 모든 키와 사각형 쌍을 얻으려면 collidedictall(rect_dict, use_values=True)를 사용하세요. {"door": door_rect, "crate": crate_rect}처럼 키로 게임 객체를 식별하면 편리합니다. 두 딕셔너리 메서드는 공식 Pygame Rect 문서에 설명되어 있습니다.

예를 들어 플레이어 사각형이 "crate"와 "door"에 해당하는 값과 겹친다면, player.collidedict(rectangles, use_values=True)는 일치하는 키와 사각형 쌍 하나를 반환하고 player.collidedictall(rectangles, use_values=True)는 두 쌍을 반환합니다. 설정된 런타임에서 Pygame을 가져오면 플랫폼별 경고가 발생하므로, 여기서는 API 호출을 인라인으로 제시합니다. 반환값은 문서에 설명된 API 동작을 나타내며 이곳에서 런타임으로 검증한 결과는 아닙니다. 어떤 충돌이든 하나면 충분할 때는 단일 일치 메서드를 사용하고, 겹치는 항목을 모두 처리해야 할 때는 전체 일치 메서드를 사용하세요. 반환된 키로 충돌한 사각형에 대응하는 객체를 찾을 수 있지만, 충돌에 어떻게 대응할지는 이 메서드가 결정하지 않습니다.

두 원이 겹치는지 확인하기

Pygame의 Rect에는 collidecircle() 메서드가 없습니다. 중심이 (x1, y1)과 (x2, y2)이고 반지름이 각각 r1, r2인 원은 중심 사이의 거리를 계산해 반지름의 합과 비교하세요. 거리가 r1 + r2 이하이면 두 원은 맞닿거나 겹칩니다. 불리언 판정에 제곱근 계산이 필요 없다면 제곱한 값을 비교하면 됩니다.

(x1 - x2) ** 2 + (y1 - y2) ** 2 <= (r1 + r2) ** 2

각 중심과 반지름이 객체의 위치에 맞게 갱신되도록 하세요. 이 계산은 충돌 영역이 원형이라는 가정에 기반하므로, 원이 아닌 스프라이트를 정밀하게 검사하지는 않습니다.

마스크로 픽셀 단위 겹침 확인하기

직사각형 히트박스만으로 투명하거나 불규칙한 스프라이트 모양을 충분히 표현할 수 없다면, 표면에서 pygame.mask.from_surface(surface)로 마스크를 만드세요. 먼저 colliderect()로 넓은 범위의 충돌을 확인하고, 두 사각형이 겹칠 때만 마스크를 만들거나 조회합니다. 그런 다음 first_mask.overlap(second_mask, offset)을 호출하세요. 오프셋은 두 번째 마스크가 첫 번째 마스크에 대해 놓인 위치입니다. 보통 (second_rect.x - first_rect.x, second_rect.y - first_rect.y)를 사용합니다. Mask.overlap()은 불투명한 픽셀끼리 겹치면 한 점을 반환하고, 마스크 픽셀이 겹치지 않으면 None을 반환합니다. 마스크 생성과 겹침 동작은 공식 Pygame mask 문서에서 확인할 수 있습니다.

마스크 검사는 사각형 검사보다 계산량이 많으므로, 정밀도가 게임플레이에 도움이 되는 경우에만 사용하세요. 표면이 바뀌지 않았다면 매 프레임 다시 만드는 대신 마스크를 캐시하세요. 마스크는 마스크 픽셀을 검사합니다. 그림자나 광택 효과는 원본 표면에 해당 픽셀이 포함되어 있지 않으면 검사 대상이 아닙니다.

간단한 독립형 기하 예제로 Pygame 창이나 이미지 에셋 없이 사각형의 겹침 여부를 보여줄 수 있습니다. 이는 순수 Python 로직이며 Pygame API를 시험하는 예제는 아닙니다.

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

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