機能仕様書: シーン分析・デバッグ機能

[akiojin]

Spec

機能仕様書: シーン分析・デバッグ機能

機能ID: SPEC-e8f7a2c1
作成日: 2025-10-17
ステータス: 完了
入力: Unityシーンの内容分析、GameObjectの詳細取得、コンポーネント検索、参照関係の調査、Animator状態取得

実行フロー (main)

1. 入力から分析要件を解析
   → 分析タイプ（シーン全体/GameObject詳細/コンポーネント/参照/Animator）の特定
2. シーン情報の収集
   → オブジェクト数、タイプ別の集計、Prefab情報
3. GameObject詳細の取得（オプション）
   → 階層、コンポーネント、マテリアル、子要素を含む詳細情報
4. コンポーネント検索（オプション）
   → 特定のコンポーネントタイプを持つGameObjectの検索
5. 参照関係の調査（オプション）
   → GameObjectへの参照、GameObjectからの参照、アセット参照
6. Animator状態の取得（オプション）
   → レイヤー、ステート、トランジション、パラメータ情報
7. メモリ情報の推定（オプション）
   → メッシュ、テクスチャ、マテリアルのメモリ使用量推定
8. 戻り値: SUCCESS（分析結果情報）

---

⚡ クイックガイドライン

• ✅ デバッグとシーン理解のための分析ツールの必要性に焦点
• ❌ 内部的なUnityのメモリ管理や最適化アルゴリズムの詳細は避ける
• 👥 ゲーム開発者・テクニカルアーティスト・AIエージェント向けに記述

---

ユーザーシナリオ＆テスト

主要ユーザーストーリー

開発者として、シーンの構成を理解し、パフォーマンス問題を特定するために、シーン内容を分析したい。AIエージェントとして、シーン内のオブジェクトとその関係性を理解したい。

受け入れシナリオ

1. 前提 複雑なシーンがロードされている、実行 シーン内容分析を要求、結果 オブジェクト数、タイプ別集計、Prefab情報が返される
2. 前提 特定のGameObjectを詳しく調べたい、実行 GameObject詳細取得、結果 階層、コンポーネント、マテリアル、子要素情報が返される
3. 前提 Lightコンポーネントを持つオブジェクトを探したい、実行 コンポーネントで検索、結果 Lightを持つGameObjectのリストが返される
4. 前提 あるGameObjectへの参照を調べたい、実行 参照関係の調査、結果 参照元と参照先のリストが返される
5. 前提 Animatorの現在状態を確認したい、実行 Animator状態取得、結果 レイヤー、ステート、パラメータ値が返される
6. 前提 メモリ使用量を推定したい、実行 メモリ情報を含めて分析、結果 メッシュ、テクスチャのメモリ推定値が返される
7. 前提 非アクティブなオブジェクトも含めたい、実行 includeInactiveオプションで分析、結果 非アクティブなオブジェクトも含まれる

エッジケース

• シーンに何もない場合、何が返されるか? → オブジェクト数0、空のリストを返す
• GameObjectが存在しない場合、どう処理するか? → エラーメッセージと代替案を提示
• 循環参照が存在する場合、どう処理するか? → 循環参照を検出し、警告を含めて返す
• Animatorがない場合、状態取得はどう処理するか? → エラーメッセージとAnimatorの追加提案を返す
• メモリ推定が不正確な場合、どう通知するか? → 推定値であることを明記し、警告を含める

要件

機能要件

• FR-001: ユーザーはシーン全体の内容を分析できる必要がある（オブジェクト数、タイプ別集計）
• FR-002: システムはタイプ別にオブジェクトをグループ化できる必要がある
• FR-003: システムは非アクティブなオブジェクトを含めるオプションをサポートする必要がある
• FR-004: システムはPrefab接続情報を含めるオプションをサポートする必要がある
• FR-005: システムはメモリ使用量推定を含めるオプションをサポートする必要がある
• FR-006: ユーザーは特定のGameObjectの詳細情報を取得できる必要がある
• FR-007: システムはGameObject詳細取得時に子要素を含めるオプションをサポートする必要がある
• FR-008: システムは詳細取得時にコンポーネント、マテリアル情報を含められる必要がある
• FR-009: システムは子要素の最大深度を指定できる必要がある（0-10）
• FR-010: ユーザーは特定のコンポーネントタイプを持つGameObjectを検索できる必要がある
• FR-011: システムはコンポーネント検索時に完全一致/派生タイプマッチを選択できる必要がある
• FR-012: ユーザーはGameObjectの参照関係を調査できる必要がある（階層/アセット/Prefab参照）
• FR-013: ユーザーはAnimatorの状態情報を取得できる必要がある（レイヤー、ステート、トランジション、パラメータ）
• FR-014: システムはAnimatorの特定レイヤーのみを取得するオプションをサポートする必要がある
• FR-015: システムはAnimatorのクリップ情報を含めるオプションをサポートする必要がある

非機能要件

• NFR-001: シーン分析は10秒以内に完了する必要がある（1000オブジェクト未満の場合）
• NFR-002: GameObject詳細取得は2秒以内に完了する必要がある
• NFR-003: コンポーネント検索は5秒以内に完了する必要がある
• NFR-004: 参照関係調査は10秒以内に完了する必要がある
• NFR-005: Animator状態取得は1秒以内に完了する必要がある

主要エンティティ

• SceneAnalysis: オブジェクト数、タイプ別集計、Prefab情報、メモリ推定を含むシーン分析結果
• GameObjectDetails: 名前、パス、階層、コンポーネント、マテリアル、子要素を含む詳細情報
• ComponentSearch: コンポーネントタイプ、マッチ設定、検索スコープを含む検索条件
• ReferenceInfo: 参照元、参照先、階層参照、アセット参照を含む参照関係情報
• AnimatorState: レイヤー、ステート、トランジション、パラメータ、IK、ルートモーションを含む状態情報

---

レビュー＆受け入れチェックリスト

コンテンツ品質

• 実装詳細なし（言語、フレームワーク、API）
• ユーザー価値とビジネスニーズに焦点
• 非技術関係者向けに記述
• すべての必須セクション完成

要件完全性

• [要明確化]マーカーが残っていない
• 要件はテスト可能で曖昧さがない
• 成功基準は測定可能
• スコープが明確に境界付けられている
• 依存関係と前提条件が識別されている

---

実行ステータス

• ユーザー説明を解析済み
• 主要概念を抽出済み
• 曖昧さをマーク済み
• ユーザーシナリオを定義済み
• 要件を生成済み
• エンティティを識別済み
• レビューチェックリスト合格

---

参考実装

実装ファイル

• unity-cli/src/handlers/analysis/AnalyzeSceneContentsToolHandler.js
• unity-cli/src/handlers/analysis/GetGameObjectDetailsToolHandler.js
• unity-cli/src/handlers/analysis/FindByComponentToolHandler.js
• unity-cli/src/handlers/analysis/GetObjectReferencesToolHandler.js
• unity-cli/src/handlers/analysis/GetAnimatorStateToolHandler.js
• unity-cli/src/handlers/analysis/GetComponentValuesToolHandler.js
• UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/SceneAnalysisHandler.cs

技術詳細

• UnityEditor.SceneManagementによるシーン情報取得
• Reflectionによるコンポーネント検索と値取得
• PrefabUtilityによるPrefab接続情報取得
• Animatorの実行時状態取得（Play mode専用機能あり）

Plan

実装計画: シーン分析・デバッグ機能

機能ID: SPEC-e8f7a2c1 | ステータス: 実装完了

概要

本機能は既に実装済みです。このplan.mdは実装完了後に作成されました。

実装状況

• ✅ Phase 0: Research完了
• ✅ Phase 1: Design完了
• ✅ Phase 2: Task planning完了
• ✅ Phase 3: Tasks実装完了
• ✅ Phase 4: 実装完了
• ✅ Phase 5: テスト完了

参考実装

実装詳細については spec.md の「参考実装」セクションを参照してください。

---

本ドキュメントは実装完了後に作成されました

Tasks

タスク: シーン分析・デバッグ機能

機能ID: SPEC-e8f7a2c1 | ステータス: 完了

実装状況

本機能は既に実装済みです。すべてのタスクが完了しています。

完了済みタスク

• 機能設計
• コア実装
• テスト実装
• ドキュメント作成

参考

実装詳細については spec.md および plan.md を参照してください。

---

本ドキュメントは実装完了後に作成されました

TDD

TODO

Research

TODO

Data Model

TODO

Quickstart

TODO

Contracts

Artifact files under contracts/ are managed in issue comments with contract:<name> entries.

Checklists

Artifact files under checklists/ are managed in issue comments with checklist:<name> entries.

Acceptance Checklist

• Add acceptance checklist