threejs-debugging

Three.js のデバッグ

まず再現してください。インストール済みソースと公式の履歴は、背景知識ではなく証拠として扱ってください。ドメインスキルは意図された仕組みを定義します。診断に形式的な画像、タイミング、リソース、またはリグレッションの証明が必要な場合は、$threejs-visual-validation を使用してください。

症状、期待される動作、正確な環境、最小限の再現手順、最初に失敗した契約、ローカルの証拠、上流の候補、固定したバージョン比較表、結論、対応、制限事項を含むケース記録を1つ維持してください。不明な値は不明と記録してください。

1. 正確な環境で再現する

失敗に影響する可能性のある環境情報をすべて記録してください。解決されたパッケージバージョン、実行時の THREE.REVISION、ロックファイルの解決結果、インポートのエントリーポイント、ブラウザー／OS、シード、アセットのリビジョン、正確なコマンドまたは操作を含めます。レンダリングまたはバックエンドに関する主張の場合は、レンダラーのクラス、初期化されたバックエンド、GPU、関連する機能も記録してください。それでも失敗する、最小かつ決定的な再現手順を作成してください。

標準の WebGPU パスに関する結論には、初期化済みの WebGPURenderer が必要であり、renderer.backend.isWebGPUBackend === true であることを確認してください。そうでない場合は、その主張を妨げている要因を記録してください。ユーザーがその分岐を明示的に要求した場合に限り、$threejs-compatibility-fallbacks に進んでください。レンダリングを伴わない API、エクスポート、アセット、またはバージョンに関する結論には、レンダラーやバックエンドの条件を課さないでください。

関連する環境の実態を記録し、その環境で再現手順を繰り返し実行して失敗が再現され、別の実行でも再現の有無を判別できる状態になれば、この手順は完了です。

2. 違反した契約と最初の失敗箇所を特定する

API の意味、数値上の不変条件、レンダリング状態の不変条件、リソースの遷移、視覚的な期待を分けてください。最終的な症状だけでなく、最初に失敗したアサーション、フレーム、パス、ドロー、ディスパッチ、リソース遷移、または診断内容を特定してください。

既知の最終正常状態と最初の異常状態を分ける、観測可能な境界が1つ特定できれば、この手順は完了です。

3. 仕組みを置き換えずに最小化する

疑わしい API、マテリアル、ジオメトリのパス、バックエンド、投影法、精度、所有権、ライフサイクルの動作を維持しながら、無関係なシステムを取り除いてください。システム間の境界では、同じ単位、フレーム／原点、所有者、間隔／周期／サンプル位相、状態の同一性、有効性／古さ／エラー、リセット、完了の意味を維持してください。

別のレンダラー、マテリアル、または表現を使えば障害箇所を絞り込める場合がありますが、元のパスが正しいことの証明にはなりません。

残った各コンポーネントが最初の失敗に関与し、疑わしい仕組みが引き続きテスト対象であれば、この手順は完了です。

4. ローカルの証拠を確認する

解決されたリビジョンについて、インストール済みのエクスポートマップ、ソース、型定義、テスト、サンプル、移行資料を確認してください。まずローカルの仮説を検証してください。アプリケーションの誤用、古いインポートまたは重複したインポート、移行による変更、レンダラーの初期化漏れ、未対応のバックエンド／機能、無効なデータ、出力変換の重複、ライフサイクル／同期のエラー、サードパーティとの統合を確認します。

考えられる各ローカル仮説について、実行可能な検証結果、または証拠が不足していることを明示した記録があれば、この手順は完了です。

5. 上流を必要に応じて調査する

ローカルの証拠だけでは原因を特定できない場合、インストール済みのソースと最新のドキュメントが食い違う場合、バージョン依存の回帰またはアップグレードが考えられる場合、あるいはユーザーが既知の問題について尋ねている場合に限り、上流を調査します。検索を始める前に 上流調査を読み、指定された一次情報源の優先順に従います。

候補ごとに個別に分類します。

分類	必要な証拠
usage-or-integration-error	インストール済みの仕様で失敗の原因を説明でき、ローカルでの修正が通る
intentional-api-change	公式の移行情報またはソースの履歴で、意図的な変更が証明されている
upstream-active	現在確認したコードで再現し、上流の記録と一致する
fixed-unreleased	該当する修正がマージ済みであり、確認した公開状況またはパッケージの内容から、記録された確認時点で未リリースであることが分かる
fixed-released	公開済みのパッケージに修正が含まれ、同じ再現テストが通る
not-reproduced	候補の構成ではローカルの失敗が再現しない
unrelated	API、バックエンド、症状、影響範囲、または再現条件が実質的に異なる
insufficient-evidence	再現、封じ込め、修正、またはリリースを証明する証拠が不足している

クローズ済みは分類ではありません。また、マージ済みであることは、その修正が npm のリリースに含まれている証拠にはなりません。レジストリを利用できない、パッケージを未確認、または公開状況が不明な場合は、fixed-unreleased ではなく insufficient-evidence とします。公開状況を示す場合は、確認時刻と確認したバージョンを記録します。候補の構成でテストが通っても、再現条件と関連環境が比較可能な状態に保たれていない限り、元の失敗が解決した証拠にはなりません。

確認したすべての候補に、裏付けのある分類がそれぞれ1つだけ付いたら、この手順は完了です。

6. バージョンに依存する場合は、バージョンマトリクスの条件を一定に保つ

診断がバージョンごとの挙動に依存する場合は、再現条件、バックエンド、ブラウザー／GPU、インポート、アセット、アサーションを一定に保ちながら、Three.js のバージョンを一度に1つだけ変更します。証拠が得られる範囲で、インストール済みバージョン、最後に正常だったバージョン、最初に問題が発生したバージョン、修正コミット、修正版を含む最初の公開リリース、現在確認できる最新リリースを記録します。

影響範囲またはリリースの提供状況に関する結論が、バージョン名ではなく比較可能な行の結果に基づいていることを確認したら、この手順は完了です。

7. 封じ込め、検証してから、対応を1つ選ぶ

まず、破られた不変条件を守るための、最も限定的な封じ込め策を特定します。次に、提案する修正を元の再現条件で検証します。修正コミット、修正を含む最初の公開済みパッケージ、そのパッケージで再現テストが通ることを証明してから、アップグレードを推奨します。

対応を1つ選びます。

• 誤用または無効な状態に対するアプリケーションの修正
• 公開済みの修正が検証された場合のアップグレード
• 適用範囲と削除条件を明記した、対象を限定する回避策またはバージョン固定
• 現在確認したコードで再現し、該当する事例がない場合の上流への報告
• 必要な証拠を得られない場合のブロッカー

選択した対応について、検証に合格しているか、または反証可能であり、対象となるバージョン／バックエンドの範囲と副作用を明記し、証拠で裏付けられる以上の主張をしていないことを確認したら、この手順は完了です。

報告して終了する

根本原因、インストール済みの環境での結果、関連する上流の issue／PR と修正コミット、影響範囲、修正版を含む最初の公開リリース、分類、修正版での結果、回帰を検出するアサーション、判断を1つ、制限事項を報告します。

1つの結論がローカルの直接的な証拠で裏付けられ、上流が関係する場合は、一次情報源またはリリースの直接的な証拠もそろった時点で終了します。妥当な候補がすべて分類され、正確にどの証拠が不足しているかが明示された場合も終了します。対応が決まった後は、無関係な issue ID を集めないでください。