hz-unity-fbx-import

完全な URL を使用した Unity の FBX インポート

外部の 3D モデルのインポートで最も多く見られる失敗の原因は、ソースパスが不完全なことです。このスキルでは、すべての FBX ソースに完全修飾 URL または絶対ファイルシステムパスを使用し、unity-cli を使ったインポート手順を説明します。

このスキルを使用する場面

次の場合は、このスキルを自動的に使用してください。

• 外部ソースから FBX ファイルをインポートするとき
• Unity プロジェクトに 3D モデルを追加するとき
• URL やファイルパスからアセットを読み込むとき
• ユーザーが「モデルをインポート」「FBX を追加」「3D アセットを読み込む」「モデルを取り込む」と言ったとき

基本原則

FBX ファイルには、必ず完全修飾 URL または絶対パスを使用してください。

相対パスや不完全な URL は使用せず、パスが補完されると想定しないでください。

unity command import_asset が受け取るのは絶対ファイルシステムパスであり、ダウンロードは行いません。 確認済みです。 URL を渡すと、"Source file 'https://…' does not exist." というエラーになります。そのため、リモートモデルの処理は必ず 2 段階になります。ディスクにダウンロードしてから、ローカルファイルをインポートします。

手順

ステップ 1：FBX ソースを特定する

ユーザーからモデルのインポートを依頼されたら、ソースを特定します。

1. リモート URL（HTTP/HTTPS）：

   • http:// または https:// で始まる必要があります
   • 完全なドメインとパスを含める必要があります
   • ファイル名は .fbx または .zip で終わる必要があります
   • 重要：拡張子の後にあるすべてのクエリパラメーターとトークンを含めてください
   • クエリパラメーター（?param=value&other=data など）は認証に必要です
   • 例：https://example.com/models/character.fbx?token=abc123&auth=xyz
   • 例：https://cdn.fbcdn.net/path/file.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz

2. ローカルファイル（ファイルシステム）：

   • 相対パスではなく、絶対パスである必要があります
   • Windows：C:/Users/name/Downloads/model.fbx
   • Unix/Mac：/home/user/models/model.fbx
   • .fbx または .zip で終わる必要があります

3. ZIP アーカイブ：

   • URL またはローカルパスを指定できます
   • FBX ファイルが含まれている必要があります。インポート前に展開してください
   • 例：https://example.com/assets.zip

ステップ 2：ソース形式を検証する

非常に重要：クエリパラメーター（?token=...&auth=... など）を含む URL では、すべてのパラメーターを含めた URL 全体を必ず指定してください。クエリパラメーターには、ダウンロードに必要な認証トークンが含まれていることがよくあります。

有効な例：

• https://cdn.example.com/assets/models/chair.fbx
• https://cdn.example.com/models/chair.fbx?token=abc123&auth=xyz789（クエリパラメーター付き）
• https://scontent.fbcdn.net/model.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz（認証付きの Meta CDN）
• http://localhost:8000/models/character.fbx
• C:/Projects/Models/tree.fbx（Windows の絶対パス）
• /home/user/assets/car.fbx（Unix の絶対パス）
• https://github.com/user/repo/releases/download/v1.0/model.zip

無効な例（絶対に使用しないでください）：

• models/chair.fbx（相対パス）
• ~/Downloads/robot.fbx（チルダ展開はサポートされていません）
• example.com/model.fbx（プロトコルがありません）
• ../assets/model.fbx（相対パス）
• model.fbx（パスがありません）

ステップ 3：リモートソースをディスクにダウンロードする

ローカルファイルの場合は、この手順を省略してください。クエリパラメーター内の & でシェルが分割しないよう、URL を引用符で囲んでください。ダウンロードが途中で切れて失敗する原因として、最もよくあるものです。

# macOS / Linux
curl -fSL "https://example.com/models/office_chair.fbx" -o /tmp/office_chair.fbx

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://example.com/models/office_chair.fbx" -OutFile "$env:TEMP\office_chair.fbx"

インポート前に、ファイルが存在し、空でないことを確認してください。.fbx として保存された途中で切れたファイルや HTML エラーページは、明確なエラーにならず、壊れたアセットとしてインポートされます。

.zip の場合は、先に展開して中の .fbx を見つけ、そのファイルをインポートしてください。

ステップ 4：ファイルをインポートする

unity status --format json          # look for state "ready"

# Validate first — reports what would be imported, writes nothing
unity command import_asset --source "C:/Users/name/Downloads/office_chair.fbx" \
  --path "Assets/Models/office_chair.fbx" --dry_run true --format json

# Then import for real
unity command import_asset --source "C:/Users/name/Downloads/office_chair.fbx" \
  --path "Assets/Models/office_chair.fbx" --format json

• --source は外部ファイルの絶対ファイルシステムパスです。
• --path は作成ルート（通常は Assets/）からの保存先相対パスで、拡張子を含めます。Assets/ のプレフィックスは省略できます。
• --confirm true が必要なのは、保存先に既存のアセットを上書きする場合のみです。
• --dry_run true は書き込みを行わずに検証して結果を報告します。ソースがユーザーから提供された場合は、必ず使用してください。

接続、--project-path、セーフモードからの復旧については、unity-cli スキルを参照してください。

Step 5: スケールとリグの種類を設定する

import_asset は、ファイルを作成時のスケールのままコピーしてインポートします。一度に「高さ H でインポート」するツールとは異なり、サイズの正規化は別の手順です。

unity command set_import_settings --asset "Assets/Models/office_chair.fbx" \
  --settings '{"globalScale": 0.46, "useFileScale": false}' --format json

globalScale は targetHeight / currentHeight として計算します。ヒューマノイドリグの場合は、animationType も Humanoid に設定します。リグが大きすぎると歪みが発生する理由と、関連する ModelImporter のフィールドについては、hz-unity-meta-movement-sdk-retargeting を参照してください。

Step 6: インスタンス化してから、実際の境界を取得する

unity command instantiate_prefab --prefab "Assets/Models/office_chair.fbx" --name office_chair --format json
unity command save_scene --format json

次に、実際の境界を読み取ります。モデルのサイズを決して推測してはいけません。bounds は計算されるプロパティなので、get_component_properties では取得できません（MeshRenderer を読み取っても、m_Materials、m_CastShadows などは返されますが、境界は返されません）。インポートした FBX では、レンダラーはインスタンス化したルートの子に配置されるため、子レンダラーの境界を統合する unity-placement スキルの GetBounds.cs を使用します。

unity command run_script --file AgentScripts/GetBounds.cs --entry GetBounds.Run \
  --args '[["office_chair"]]' --format json

サイズと中心をユーザーに伝え、その後の位置設定にはこれらの値を使用します。

Step 7: ユーザーに報告する

• インポートが正常に完了したことを確認します
• アセットのパスと、インスタンス化された GameObject の名前を示します
• 測定したサイズと中心を示します
• 次の手順（配置、スケーリング、マテリアルの割り当て）を提案します

ユーザーが指定したパスの処理

ユーザーが不完全なパスを指定した場合

ユーザーから不完全なパスが渡された場合は、完全なパスを確認します。

ユーザー：「models/car.fbx をインポートして」

確認を求めます： 「FBX ファイルの完全なパスが必要です。次のどちらでしょうか。

• リモート URL ですか？（例：https://example.com/models/car.fbx）
• ローカルファイルですか？絶対パスを指定してください（例：C:/Projects/models/car.fbx）

car.fbx の完全なパスを教えてください。」

ユーザーがプロトコルなしの URL を指定した場合

ユーザー：「example.com/models/chair.fbx からインポートして」

プロトコルを確認します： 「次のどちらでしょうか。

• https://example.com/models/chair.fbx（HTTPS）
• http://example.com/models/chair.fbx（HTTP）

どちらのプロトコルを使用しますか？」

ユーザーが相対パスを指定した場合

ユーザー：「../models/tree.fbx をインポートして」

絶対パスを求めます： 「相対パスはサポートされていません。tree.fbx の絶対パスを指定してください。

例：

• Windows：C:/Projects/models/tree.fbx
• Mac/Linux：/home/user/projects/models/tree.fbx

完全なパスを教えてください。」

ベストプラクティス

1. ダウンロードまたはインポートの前に、必ずソース形式を確認する
2. パスを決めつけない — 明示的に指定されたパスを必ず使用するか、確認を求める
3. あらゆる形式の相対パスよりも、絶対パスを優先する
4. すべてのリモート URL にプロトコル（http://、https://）を含める
5. クエリパラメーターの & がジョブの区切りとして扱われないよう、シェルでは URL を引用符で囲む
6. ファイル拡張子を検証する — .fbx または .zip である必要がある
7. ユーザーが指定したソースには、最初に --dry_run true を使用する
8. インポート前に、ダウンロードしたファイルが空でないことを確認する
9. インスタンス化後に境界を測定する — モデルのサイズを決して推測しない
10. unity-placement と連携する — 測定した境界を位置設定に使用する
11. デバイスで抜き取り確認を行う — クリーンな状態でインポートした後、デプロイして metavr capture screenshot を取得し、Editor 上だけでなくヘッドセット内でもモデルが正しく見えることを確認する

エラー防止チェックリスト

インポート前に、次の項目を確認してください。

• ソースが完全な URL または絶対パスである
• リモート URL にプロトコル（http:// または https://）が含まれている
• すべてのクエリパラメーターが含まれている（URL の ? 以降のすべて）
• URL がシェルコマンド内で引用符で囲まれている
• ローカルパスが絶対パスである（C:/ または / で始まる）
• 相対パスの要素が含まれていない（../ または ./ がない）
• チルダ展開を使用していない（~/ がない）
• ファイル名が .fbx または .zip で終わっている（後ろにクエリパラメーターが続く場合を除く）
• リモートソースが先にディスクへダウンロードされ、ファイルが空でない
• --path の保存先に拡張子が含まれている
• 既存のアセットを上書きする場合は --confirm true が指定されている
• モデルが実寸で作成されていない場合は、set_import_settings でスケールが正規化されている

代替手段：MCP のワンショットインポーター

Meta Unity 拡張機能を備えた Unity MCP サーバーは、Unity_ImportExternalModel を公開します。このツールは、ダウンロード、インポート、高さの正規化、テクスチャの割り当て、プレハブの作成を 1 回の呼び出しで行います。コマンドカタログには同等の機能がないため、MCP 経由でのみ利用できます。パラメーター、有効化する設定、手動での Unity_RunCommand による再実装については、references/unity-mcp-fallback.md を参照してください。

クイックリファレンス

ソースに必要な形式

ソースの種類	形式	例	先にダウンロードが必要か
リモート HTTPS	https://domain/path/file.fbx	https://cdn.example.com/models/chair.fbx	はい
リモート HTTP	http://domain/path/file.fbx	http://localhost:8000/model.fbx	はい
ローカル Windows	C:/path/to/file.fbx	C:/Users/name/Downloads/robot.fbx	いいえ
ローカル Mac/Linux	/path/to/file.fbx	/home/user/models/tree.fbx	いいえ
ZIP アーカイブ	上記と同じ形式で、末尾に .zip を付ける	https://example.com/pack.zip	はい。さらに展開も必要

他のスキルとの連携

• unity-placement：インポート後の配置には、測定した境界を使用します。
• hz-unity-meta-movement-sdk-retargeting：キャラクターモデルのインポートスケールと Humanoid リグタイプを設定します。
• unity-cli：Editor への接続、--project-path、Safe Mode からの復旧に使用します。

覚えておくこと

インポートの失敗は、ほとんどの場合パスの問題です。判断に迷った場合は、次の手順に従ってください。

1. ユーザーに完全なパスを尋ねます
2. ダウンロードする前に形式を確認します
3. リモート URL にはプロトコルを含め、URL 全体を引用符で囲みます
4. リモートファイルは import_asset の前にディスクへダウンロードします。URL の取得は行いません
5. --source には絶対パスを使用します
6. 不完全なパスを推測したり、自動補完したりしないでください
7. 相対パスやチルダ展開は使用しないでください