HOWTO · Pygame

Pygame で衝突を検出する

このチュートリアルでは、衝突テストや Pygame での検出に使用できるさまざまな方法について説明し、紹介します。

このページの内容

必要な形状と判定結果に応じて、Pygameの衝突検出方法を選びます。位置と矩形の判定には collidepoint()、2つの矩形には colliderect()、複数の矩形の検索には collidelist() または collidedict() を使います。円の場合は、中心間の距離と半径を比較します。不規則なスプライトには、矩形による広域判定とマスクの重なり判定を組み合わせます。以下では各APIの動作を説明します。コード例はゲームループ全体を示すものではありません。補足として collidelistall()、collidedictall()、pygame.mask.from_surface() も取り上げます。

用途に合った衝突判定を選ぶ

ゲームに合う方法のうち、計算コストが最も低いものから使いましょう。矩形判定は高速で、足場、壁、当たり判定用の領域には十分なことがよくあります。マウスでの選択には点の判定が使えます。リストや辞書向けのメソッドは複数の矩形を検索し、該当する位置やキーを返します。丸いオブジェクトには円の計算が適しています。マスクは不透明なピクセルを調べるため、より正確ですが計算コストが高くなります。

pygame.Rect は矩形の位置とサイズを保持します。Pygameの衝突判定メソッドが返すのは幾何学的な重なりの結果であり、オブジェクトを移動したり衝突を解決したりはしません。その結果を使って、移動を止める、アイテムを取得する、ボタンを開くといったゲーム内の処理を決めます。

点が矩形の内側にあるか調べる

rect.collidepoint(x, y) のように座標を個別に渡すか、rect.collidepoint((x, y)) のように1組の座標として渡します。点が矩形の内側にある場合は True、そうでない場合は False を返します。たとえば、現在のマウス位置を渡してホバー状態を判定し、結果が真ならボタンの見た目を変えられます。Rect の衝突判定では右端と下端は範囲に含まれないため、その辺上の点は矩形の外側として扱われます。

2つの矩形が重なっているか調べる

2つの pygame.Rect オブジェクトを作成し、first.colliderect(second) を呼び出します。結果は真偽値なので、そのまま if 文で使えます。たとえば player_rect.colliderect(wall_rect) で、プレイヤーの当たり判定領域が壁と交差しているかを調べられます。辺が接しているだけの矩形は重なりとは判定されません。この方法は高速ですが、矩形の当たり判定領域にスプライトの透明部分が含まれることがあります。

リスト内の矩形との衝突を調べる

1つの矩形を複数の矩形からなる並びと比較するには、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) を使うと、一致したキーと矩形の組を1つ取得できます。一致する矩形がなければ None が返ります。辞書の値に矩形を格納している場合は、引数 use_values=True が必要です。これを省略すると、メソッドはキーを矩形のような値として調べるため、通常の文字列キーでは TypeError が発生します。一致した組をすべて取得するには collidedictall(rect_dict, use_values=True) を使います。{"door": door_rect, "crate": crate_rect} のように、キーでゲームオブジェクトを識別するときに便利です。2つの辞書用メソッドについては、公式の Pygame Rect ドキュメントで確認できます。

たとえば、プレイヤーの矩形が "crate" と "door" に対応する値の両方と重なる場合、player.collidedict(rectangles, use_values=True) は一致したキーと矩形の組を1つ返し、player.collidedictall(rectangles, use_values=True) は両方の組を返します。設定された実行環境でPygameをインポートすると環境固有の警告が出るため、APIの呼び出しは本文中の例として示しています。結果はドキュメントに記載されたAPIの動作を表しており、ここでは実行確認していません。どれか1つの衝突が分かればよい場合は単一一致用のメソッドを使い、重なりをすべて処理する必要がある場合は全一致用のメソッドを使います。返されたキーから該当するオブジェクトを特定できますが、衝突への対応そのものは決まりません。

2つの円が重なっているか調べる

Pygameの Rect に collidecircle() メソッドはありません。中心が (x1, y1) と (x2, y2)、半径が r1 と r2 の円では、中心間の距離を求め、半径の合計と比較します。距離が r1 + r2 以下なら、円は接しているか重なっています。真偽値だけが必要なら、平方根の計算を避けるため、両辺を2乗して比較できます。

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

各円の中心と半径は、オブジェクトの位置に合わせて更新してください。この計算が想定するのは円形の当たり判定領域です。円形ではないスプライトを正確に判定する方法ではありません。

マスクでピクセル単位の重なりを調べる

透明部分のあるスプライトや不規則な形状に対して矩形の当たり判定が粗すぎる場合は、pygame.mask.from_surface(surface) でサーフェスからマスクを作成します。まず colliderect() で広域判定を行い、矩形が重なる場合にだけマスクを作成または照会します。その後、first_mask.overlap(second_mask, offset) を呼び出します。offset は2つ目のマスクの位置を1つ目に対する相対位置で表した値で、一般には (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