webg

衝突判定とクエリ

本章では、画面上の位置からシーン内のShapeを選ぶレイキャストと、シーン内の物体同士が重なる可能性を調べる衝突判定を説明します。 すべての判定をワールド座標へ揃え、まず広域判定で候補を絞り、必要な場合だけ詳細判定へ進みます。 選択と衝突という目的の違いに応じて、必要な精度と計算量の判定方法を選べるようにします。

この章の読み方

この章を読む前に必要な知識

03章の座標変換と05章のSpace・Nodeを知っていると読みやすくなります。

初回に読む範囲

レイキャストと重なり判定の違い、Space.raycast、checkCollisionsの基本例を先に読んでください。

必要になったときに読む範囲

詳細判定、クリック位置との接続、結果の扱い、物理的な押し戻しとの違いは必要時に参照してください。

この章を終えた時点でできること

視線上の対象と空間内の重なりを、目的に応じた問い合わせAPI(Application Programming Interface:プログラムから機能を呼び出す接続方法)で調べられます。

レイキャストと重なり判定を使い分ける

画面上で選んだ位置から3D空間の対象を探す場合はレイキャストを使い、シーン内のShape同士が重なっているかを調べる場合は衝突判定の問い合わせを使います。 本章では、判定の起点と必要な精度からAPIを選び、広い範囲の候補を調べる処理と、三角形まで確認する詳細判定を使い分けます。

本章で扱うのは、レイキャストと形状の重なりを調べる問い合わせAPIです。 接触後の押し戻し、反発、摩擦、継続的なボディ更新は27〜28章の物理エンジンが担当します。

ユーザーからの入力を受け取れるようになると、次に必要になるのは「その入力が3D空間の何に当たったのか」、あるいは「シーン内の何と何が重なったのか」を判断することです。

クリックしてオブジェクトを選択したいのか、オブジェクト同士の接触を調べたいのかによって、使用するAPIは異なります。 webg では、これらの役割を Space.raycast()、Space.checkCollisions()、および Space.checkCollisionsDetailed() が分担して担っています。

ここで重要なのは、これらがすべて「判定」に関するAPIであっても、判定の起点が異なるという点です。 raycast() は1本のレイ(光線)を飛ばして何に当たるかを調べるAPIであり、checkCollisions 関連のAPIはシーン内のシェイプ同士が重なっているかを調べるものです。

本章では、単にAPI名を覚えることではなく、「どのような判定を行いたいときに、どのAPIを選択すべきか」という基準を整理して解説します。

ここで扱うのは主に「当たっているかを調べる」ための問い合わせです。 接触した後にどう押し戻すか、反発や摩擦で速度をどう変えるか、回転付きのボックスをどう扱うかといった物理応答は、27章「物理エンジンを使う」と28章「物理イベント、設定、更新」で扱います。

なお、現在の webg の実装では、raycast() と checkCollisions() はまずAABB(軸並行境界ボックス)ベースで動作します。 そのため、非常に細い棒や斜めの円柱のような形状の場合、見た目よりも少し大きめの範囲でヒット判定が出る場合があります。 より厳密な判定が必要な場合には、広域判定の後に三角形レベルでの絞り込みを行う checkCollisionsDetailed() を使用します。

また、どのAPIを使用する場合でも、filter を適切に設定することで、カメラ自身や補助用のシェイプを判定候補から除外でき、結果をより正確に得ることができます。

クリック位置から Space.raycast() へつなぐ

Space.raycast() は、レイの起点(オリジン)と方向を受け取り、ヒットしたシェイプを返します。 このAPIはワールド空間のレイの起点と方向を受け取ります。マウスやタップの画面座標は、まずNDC(Normalized Device Coordinates:正規化デバイス座標)へ変換し、投影行列とビュー行列からワールド空間のレイへ変換します。 unittest/raycast にはこの一連の流れが実装されており、実装例として非常に参考になります。

画面上のX座標とY座標は、canvasの表示範囲をそれぞれ-1から1へ変換します。 一方、奥行きを表すWebGPUのNDC depthは0から1です。 通常カメラに使うCamera Reverse-Zでは、near planeが1、far planeが0です。OpenGLのdepth=-1をnearとして扱う規約とは異なるため、深度値をコードへ直接書かず、CAMERA_REVERSE_Zの定義を参照して描画と逆投影の規則をそろえます。

import Matrix from "./webg/Matrix.js";
import { CAMERA_REVERSE_Z } from "./webg/DepthConvention.js";

// 画面上の座標(CSS ピクセル)を正規化デバイス座標(NDC)に変換する
const cssToNdc = (canvas, clientX, clientY) => {
  const rect = canvas.getBoundingClientRect();
  const x = ((clientX - rect.left) / rect.width) * 2.0 - 1.0;
  const y = 1.0 - ((clientY - rect.top) / rect.height) * 2.0;
  return [x, y];
};

// マウス位置から 3D 空間へのレイを生成する
const makeRayFromMouse = (canvas, clientX, clientY, eyeNode, proj, view) => {
  const [nx, ny] = cssToNdc(canvas, clientX, clientY);
  const invVp = proj.clone();

  // projectionは透視成分を持つため、4×4の全要素を計算する
  // Matrix.mul()は回転と平行移動を扱う剛体変換向けなので使用しない
  invVp.mul_(view);
  invVp.inverse_strict();

  // WebGPUのdepthは0..1で、Camera Reverse-Zではnear=1、far=0
  const near = invVp.mulVector([
    nx,
    ny,
    CAMERA_REVERSE_Z.nearDepth
  ]);
  const far = invVp.mulVector([
    nx,
    ny,
    CAMERA_REVERSE_Z.farDepth
  ]);
  const eyePos = eyeNode.getWorldPosition();
  const dir = [
    far[0] - eyePos[0],
    far[1] - eyePos[1],
    far[2] - eyePos[2]
  ];
  return { origin: eyePos, dir, near, far };
};

canvas.addEventListener("click", (ev) => {
  // カメラのワールド行列を最新の状態に更新する
  app.eye.setWorldMatrix();
  const view = new Matrix();
  view.makeView(app.eye.worldMatrix);

  const ray = makeRayFromMouse(
    app.screen.canvas,
    ev.clientX,
    ev.clientY,
    app.eye,
    app.projectionMatrix,
    view
  );

  // レイキャストを実行し、最初に当たったオブジェクトを取得する
  const hit = app.space.raycast(ray.origin, ray.dir, {
    firstHit: true,
    // カメラ自身や非表示のシェイプを判定から除外するフィルタ
    filter: ({ node, shape }) => node !== app.eye && !shape.isHidden
  });

  if (!hit) {
    return;
  }
  console.log(hit.node.name, hit.point, hit.t, hit.boundsOnly);
});

この実装で最初に確認する点は、projectionとviewの合成方法です。 Matrix.mul()とMatrix.lmul()は、回転と平行移動からなる剛体変換を効率よく合成するメソッドです。透視投影行列の4行目を含む逆view-projection行列には、4×4の全要素を計算するMatrix.mul_()を使います。 ここでmul()を使用すると、クリックイベントとNDC座標が正しくても、生成されたレイが画面上の物体とは異なる方向へ進みます。

次に確認する点は、逆投影へ渡すdepthです。 Camera Reverse-ZではCAMERA_REVERSE_Z.nearDepthが1、CAMERA_REVERSE_Z.farDepthが0です。 nearとfarをそれぞれ逆投影すると、視点とクリック位置を通る同じ直線上のワールド座標が得られます。 透視投影では視点をレイの起点とし、視点からfar plane上の点へ向かうベクトルを方向として使用します。

また、raycast() を呼び出す前に app.eye.setWorldMatrix() と view.makeView(app.eye.worldMatrix) を実行する必要があります。 レイを生成する基準となる視点行列が古いままでは、画面上のクリック位置と3D空間での方向がずれてしまいます。 また、filter を活用することで、不要なオブジェクトを候補から排除し、効率的な判定が可能になります。

raycast() は内部的に方向ベクトルを正規化し、各シェイプのローカル境界ボックスをワールドAABBへ変換して判定を行います。 戻り値の point はレイ上のワールド座標であり、boundsOnly: true は「メッシュ表面そのものではなく、境界ボックスベースでのヒットであること」を示しています。 クリックによるオブジェクト選択や大まかなヒットテストには十分な精度ですが、厳密な表面判定とは異なります。 現在の webg における raycast() は、「精密な表面判定」というよりも「選択UI(User Interface:利用者との操作・表示の接点)のための入り口」として活用するのが適切です。

Reverse-Zが関係するのは、画面上の位置とdepthからワールド空間のレイを復元する段階までです。 Space.raycast()へ渡した後は、方向正規化、ワールドAABBの作成、レイとAABBの交差判定をワールド座標で進めます。depth bufferのnearとfarは画面座標からレイを復元する段階で使います。 同様に、後述するcheckCollisions()とcheckCollisionsDetailed()もワールド座標の形状を比較するため、Reverse-Zとは独立した判定方法になります。

シーン内の重なりを調べる

シーン内のオブジェクト同士が一括して重なっているかを調べたい場合は、レイキャストではなく衝突判定(Collision)関連のAPIを使用します。 samples/collisions では、移動するオブジェクトと複数のシェイプを組み合わせ、この判定の違いを確認できるようになっています。

衝突判定の基本的な考え方は、「まず広域判定で候補を絞り込み、必要に応じて詳細判定へ進む」という2段構えの構成です。

checkCollisions() による広域判定

まず使用するのは checkCollisions() です。

const collisions = app.space.checkCollisions({
  firstHit: false,
  filter: ({ node, shape }) => {
    if (!shape || shape.isHidden) return false;
    // 地面(ground)は判定対象から除外する
    return node.name !== "ground";
  }
});

for (let i = 0; i < collisions.length; i++) {
  const pair = collisions[i];
  console.log(pair.nodeA.name, pair.nodeB.name, pair.boundsOnly);
}

このAPIは、各シェイプのワールドAABBを生成し、それらが重なっているペアを列挙します。 firstHit: true に設定すれば最初に見つかった1件のみを返しますが、挙動の確認やデバッグにおいては、全件を配列で取得したほうが全体の流れを把握しやすくなります。 ここでも filter を用いて地面や非表示シェイプを除外しておくことで、「意図しないオブジェクトに当たっている」という混乱を防ぐことができます。

checkCollisionsDetailed() による詳細判定

AABBによる判定は広域的なものであるため、斜めに配置された細長い形状などでは、見た目以上に多くの候補が検出されることがあります。 より精緻な判定が必要な場合に checkCollisionsDetailed() を使用します。

const detailed = app.space.checkCollisionsDetailed({
  firstHit: false,
  maxTrianglePairs: 80000,
  filter: ({ node, shape }) => {
    if (!shape || shape.isHidden) return false;
    return node.name !== "ground";
  }
});

for (let i = 0; i < detailed.length; i++) {
  const pair = detailed[i];
  console.log(
    pair.nodeA.name,
    pair.nodeB.name,
    pair.boundsOnly,
    pair.detailedSkipped === true
  );
}

checkCollisionsDetailed() は、広域判定を通過したペアに対して、三角形同士の交差判定を追加で行います。 ただし、三角形の数が極端に多い場合に計算量が急増するため、maxTrianglePairs を超えたペアについては詳細判定をスキップし、boundsOnly: true および detailedSkipped: true というフラグを付けて返します。

したがって、常に詳細判定版を呼び出すのではなく、まずは checkCollisions() で候補の量を確認し、必要な場面に限定して詳細判定を行う運用が効率的です。

判定APIの使い分けまとめ

どのAPIを選択すべきかは、目的とする操作によって決まります。

注意点

判定APIへ渡すベクトル、座標空間、Shapeの更新時点を揃えると、見た目と交差判定結果のずれや、不正な方向ベクトルによる判定失敗を防げます。 次の項目は、レイキャストと衝突判定の問い合わせのどちらにも共通する入力条件です。

まず、raycast() および衝突判定系APIは、すべて最新のワールド行列を前提として動作します。 オブジェクトの移動や回転を更新した直後に判定を行う場合は、フレーム内の更新順序を正しく管理してください。 特にカメラ側で app.eye.setWorldMatrix() を忘れると、生成されるレイが古い姿勢を向いてしまい、判定位置がずれる原因となります。

クリックイベントを受け取れているのにヒットしない場合は、HUDやログへNDC座標とレイdirectionを表示すると、入力の問題と逆投影の問題を分けて確認できます。 NDCがクリックに応じて変化している場合は、projectionとviewをmul_()で合成しているか、Reverse-Zのnear=1とfar=0を使っているかを確認してください。

次に、現在の raycast() と checkCollisions() がAABBベースであるという点を意識してください。 戻り値の boundsOnly フラグは、その判定が「メッシュ表面の厳密なヒット」ではなく「境界ボックスのヒット」であることを示しています。 細い棒状のオブジェクトや、斜めに配置された円柱、あるいは中空の形状の付近では、見た目と判定位置にわずかな乖離が生じることがあります。 この特性を理解しておくことで、「当たっているように見えるのに反応しない」あるいはその逆といった混乱を避けることができます。

また、filter を設定せずに使用すると、カメラ自身や補助用シェイプ、非表示オブジェクトまで判定候補に含まれてしまい、意図した結果が得られにくくなります。 開発の初期段階から node !== app.eye や !shape.isHidden、あるいは特定の地面オブジェクトを除外するといった条件を組み込んでおくことで、サンプルコードを実用的なアプリケーションへと発展させやすくなります。

関連サンプル

本章の内容を具体的に確認するには、以下のサンプルおよびユニットテストが適しています。

ユーザー入力との連携については、14章「タッチ機能と入力」を合わせて参照してください。 タップとドラッグを同一キャンバスで共存させる実装の流れを把握できます。

選択をゲームのルールへ接続する

samples/fantasy/main.jsのmakePointerRay()とpickTile()では、 画面座標からレイを作り、地形とユニットのAABBを選択します。 カメラのprojectionとviewは、頭上ラベルのupdateLabels()にも使います。 ドラッグの終了をクリックとして扱わず、補助盤のボタンも同じchoose()へ接続します。

raycastは表示物を選ぶためのクエリです。移動の可否や攻撃の射程は rules.mjsでマス座標から判定します。形状の境界と戦闘規則を分けて読む場合は、 PBRシーンから小さなゲームへ.mdとsamples/fantasy/README.mdを参照してください。

まとめ

画面から Shape を選ぶ場合は、レイキャストを使います。 オブジェクト同士の重なりには、衝突クエリを使います。 広域判定で候補を絞り、必要な場合だけ詳細判定へ進みます。 これにより、目的に合う精度と負荷を選べます。

判定データはワールド座標で揃えます。 判定データはワールド座標のまま保存し、描画時だけカメラ相対座標へ変換します。 最新のワールド行列、フィルター、判定範囲を明示することが、見た目と結果を一致させる要点です。