game-spatial-queries について
ゲーム開発者やゲーム制作エージェント向けに、ピッキング、衝突、包含判定、距離などの空間クエリを制約と境界ケースに分けて整理するスキルです。ローカル座標系、数値方針、退化形状への対処、テストを重視します。
主な機能
- 01レイと三角形の交差判定
- 02三角形内の点の判定方法
- 03平面までの符号付き距離
- 04線分上の最近点クエリ
- 05退化形状と境界の方針
- 06ジオメトリのテスト項目
活用シーン
- 01レイによるオブジェクト選択の実装
- 02点が三角形内にあるかの判定
- 03点から平面までの符号付き距離の測定
- 04衝突と最近点の境界ケースのテスト
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/game-spatial-queriesを入力して読み込まれたか確認します。
詳細
ゲームの空間クエリ
ゲームのピッキング、衝突、内外判定、距離に関する質問を、明示的な制約と失敗ケースを備えた小さな幾何システムに変換するために、このスキルを使用します。
主な出典：Oleksandr Kaleniuk 著『Geometry for Programmers』 (https://www.manning.com/books/geometry-for-programmers)。特に第3章、第4章、第9章をもとに、変換および言い換えています。追加の出典：「Fast, Minimum Storage Ray-Triangle Intersection」、Tomas Moller と Ben Trumbore 著 (https://dl.acm.org/doi/10.1145/1198555.1198746)。
基本的なワークフロー
- クエリを述語または測定値として明示します。例：ヒット／ミス、内側／外側、最短距離、符号付きの側、交点、パラメーター値。
- 可能であれば、最も単純なローカル基底に移します。三角形、線分、平面、オブジェクトローカルの基底を使うと、クエリが境界チェックだけで済むことがよくあります。
- まずパラメーターを導出し、その後で制約を適用します。大きな式に埋もれさせず、コード内で制約を明示します。
- 縮退を示す分母、向き、長さの値を特定します。
- 数値処理方針を選びます。厳密な整数述語、スケールを考慮したイプシロン、境界を含む判定、境界を含まない判定、保守的なフォールバックなどです。
- ヒット、ミス、境界、平行、縮退、ほぼ縮退のケースをテストします。
- クエリがゲームプレイの感触に影響する場合は、デバッグ用の可視化を追加します。
クエリのパターン
レイと三角形の交差
レイを R = P + t*d（t >= 0）としてモデル化します。三角形の点を
S = A + u*AB + v*AC（u >= 0、v >= 0、u + v <= 1）としてモデル化します。
R = S を解き、次の処理を行います。
- 共通分母がゼロ、または数値処理方針で定めた値より小さい場合は棄却します。
t < 0の場合は棄却します。u < 0、v < 0、またはu + v > 1の場合は棄却します。- 必要に応じて、ヒット距離
t、重心座標に似たパラメーターuとv、ヒット位置を返します。
三角形の内外判定
次のいずれかの方法を選びます。
- 三角形をローカル基底に変換し、
0 <= u、0 <= v、u + v <= 1をチェックします。 - 2D 外積から一貫した辺の向きの符号を使用します。
- 呼び出し側で補間の重みも必要な場合は、重心座標を使用します。
辺上の点を内側とみなすかどうかを決めます。テストでは、選択した辺の扱いと、三角形の頂点順序を逆にした場合の両方をカバーする必要があります。
平面に対する点の符号付き距離
平行でない2つの辺から平面の法線を作ります。正規化した法線と、平面上の任意の点からクエリ点へのベクトルとの内積を求めます。側が重要な場合は符号を保持し、符号なし距離の場合のみ絶対値を取ります。
線分と最近点のクエリ
線分の方向に射影し、パラメーターを [0, 1] にクランプしてから、クランプした点までの距離を測定します。正規化する前に、長さがゼロの線分を棄却するか、特別に処理します。
縮退したジオメトリの方針
- 長さがゼロのベクトルは正規化しないでください。
- 縮退した三角形から不安定な基底や法線が生じないようにしてください。
- レイと平面が平行な場合は、意図した結果を定める必要があります。ヒットなし、同一平面上のケースとして処理、またはフォールバッククエリのいずれかです。
- 非常に小さい分母には、スケールを考慮した方針が必要です。スケールの異なるワールド全体に固定イプシロンを使うのは、多くの場合適切ではありません。
- 境界を含めるかどうかはゲームプレイに合わせます。選択ツールでは境界を含む判定が適していることが多く、衝突の分離では保守的な判定が適していることがよくあります。
実装チェックリスト
- 関数名に、ジオメトリの種類と境界の扱いが示されています。
- 入力の座標空間と単位を説明しています。
- 頂点順序の前提が明示されています。
- 除算の前に、分母と長さがゼロの場合を処理しています。
- 戻り値の型に、呼び出し側が必要とする十分な情報が含まれています。例：bool、距離、ヒット位置、法線、重心の重み、棄却理由。
- テストに、通常ケース、ミス、辺／頂点、頂点順序の逆転、平行、縮退、スケールの大小のケースが含まれています。
よくある間違い
- オブジェクトローカル座標なら簡単に済むのに、グローバル空間でクエリを計算してしまうこと。
- 後からヒット距離や法線が必要になるクエリで、
boolのみを返すこと。 - 方針を決めずに、浮動小数点数を 0 と比較すること。
- 法線と重心座標は頂点の巻き順に依存することを忘れること。
- 「ヒットしなかった」と「入力ジオメトリが無効」を、同じデバッグシグナルとして扱うこと。