add-3d-models

Decentraland シーンへの 3D モデルの追加

ルール：モデルを配置する前にバウンディングボックスを確認する

モデルの Transform.position はローカル原点であり、見た目の範囲ではありません。 植生や大きな構造物のモデルは、原点から 6～12 m 以上伸びていることがよくあります。x=2 に配置した木が x=-10 に描画され、シーンの境界外となって見えなくなることがあります。

GLB モデルを配置する前に、実際のワールド空間のバウンディングボックスを特定してください。 生のアクセサーの min／max 値だけでは不十分です。多くのモデルでは、ノードレベルの大きなスケールがすでに反映されています。ノード変換を必ず考慮してください。 {baseDir}/references/model-patterns.md にあるバウンディングボックスのスクリプトを使用してください。

次に、安全な配置範囲を計算します：safeMinX = -bbox.minX + edgeMargin (>=1m) など。原点は安全範囲内にのみ配置してください。バウンディングボックスが不明な場合は、木や大型の葉物にはすべての辺から保守的に 12 m のバッファーを設け、小道具には 3 m のバッファーを設けてください。

ルール：ワールド座標にベイクされたジオメトリは、DCL の軸で境界を確認し、まず軸を調べる

上記のバウンディングボックスのルールは、モデルが自身の原点を基準に作られ、Transform で配置されることを前提としています。ワールド空間での配置をメッシュにベイクした時点で、たとえばゾーン全体の床や壁のチャンクを結合した場合、キットバッシュしたレイアウトを 1 つの GLB として書き出した場合、エンティティの Transform ではなく Blender のスクリプトで配置した場合など、モデルの配置はエクスポーターの軸規約に依存します。軸を誤って推測すると、読み取れる数値がすべて正しく見えるにもかかわらず、ジオメトリがシーンの外に配置されます。

発生した失敗例、2026-10-08（約 1.5 時間の損失）： シーンの境界で描画がクリップされるため、パーセルの外に出たメッシュの部分だけが消え、モデルの残りは表示されたままになります。軸の推測が誤っていても気づきにくいのはそのためです。ベイク済みのメッシュ全体が外に配置されると（たとえば X 軸で反転した場合）、エラーが出ないままメッシュ全体がクリップされます。その場合も、エンティティ自体の Transform.position はシーン内にあります。Explorer と Creator Hub エディターはどちらも同じようにクリップします。また、Creator Hub の get_scene_metrics.entitiesOutOfBoundaries にも表示されませんでした。Bevy レンダラーではこのリストはハードコードされた空の配列であるため（インスペクターの BevyRenderer で確認済み）、警告が出ることはありません。Babylon では境界に基づいて判定されるため、警告が表示されます。次の 2 つの読み取り結果に矛盾があることが手がかりです。

• explorer_get_scene_content_stats ではモデルの三角形がカウントされるため、GLB の読み込みは成功しています。
• explorer_get_scene_content_breakdown ではソースに N 個の renderers が表示され、どの視点でも visibleRenderers: 0 となっています。
• シーンログに問題はありません。

サイズが原因ではありません。同じシーンで、36 × 30 m のメッシュを境界内に完全に収めたところ、正常に描画されました。

そのため、本番用のものをベイクする前に、低コストの非対称なプローブを書き出して確認してください。 対称なボックスでは何もわかりません。反転や回転の誤りが見えないためです。片側が明確に区別できるモデルを使ってください。たとえば、+X に沿った短いバーと、長さの異なる +Z に沿ったバーを組み合わせるか、端が 1 つ開いたアセットを使います。既知の位置に配置し、ワールド内で確認してください（unity-explorer-mcp）。既知のカメラ位置からスクリーンショットを撮る、モデルに向かって歩き、explorer_get_player_state からブロックされた位置を確認する、またはその両方を行います。その後で初めて、全体をベイクしてください。使い捨ての書き出しを 1 回行うほうが、キットを再度ベイクするよりはるかに安く済みます。

Blender から DCL への軸マッピングと place() ヘルパーについては、{baseDir}/references/blender-authoring.md を参照してください。また、{baseDir}/references/model-patterns.md のバウンディングボックス用スクリプトが出力するのは glTF の軸であり、すべてのコンポーネントで DCL の軸と一致するわけではないことにも注意してください。シーンの境界と比較する前に変換してください。

ルール：隣接するエンティティを配置する前に、モデルの奥行きを考慮する

原点が異なるというだけで、2 つのモデルが重ならないとは限りません。origin +/- extent が隣接モデルのバウンディングボックスと交差しないことを必ず確認してください。奥行きのあるアーチやゲートウェイのモデル（+/-Z 方向に 14 m 伸びることがあります）や、回転したモデル（Y 軸を中心に 90 度回転させると、X と Z の範囲が入れ替わります）には特に注意してください。

ルール：三人称カメラに合わせて屋内空間を広くする

このガイダンスの正式版です。他のスキルでは数値を繰り返さず、ここにリンクしてください。 これは実践に基づく設計ガイダンスです（2026-10-08、Explorer でシーンを歩いた Decentraland スタッフからのフィードバック）。エンジンの定数ではありません。

Decentraland は主に、アバターの後方かつ上方に位置するデフォルトの三人称カメラでプレイされます。そのため、屋内空間は実際の寸法から想像するよりも、画面上でかなり狭く感じられます。カメラが天井に迫り、アバターが画面を占めるため、一般的な部屋も廊下のように見えます。現実的なスケールで部屋を作らないでください。 空間の外郭には、実際の寸法の約1.5～2倍の高さの余裕を持たせてください。

要素	現実の寸法	建築時の寸法
天井高	2.5～3 m	5～6 m
主要ルート上の出入口／開口部	約2.1 m × 0.9 m	高さ約4 m、幅3 m以上
廊下の幅	1.2～1.8 m	4 m以上
アバターが通り抜ける必要のあるすき間	—	有効幅1.2 m以上

• 手に取れるサイズの小道具は人間のスケールに保ってください。 椅子、机、カウンター、手すり、画面、標識はおおむね実物大にし、部屋の中でアバターが人として見えるようにします。空間の外郭に合わせて家具も大きくすると、窮屈な印象がそのまま一回り大きくなるだけです。大きくするのは部屋であり、中身ではありません。
• カタログモデルのスケールを調整する場合も同様です。 以下のモデル置き換え監査では、元のサイズを基に scale を決めます。建築物では、現実的なサイズではなく、大きめの寸法を目標にしてください。
• これらの数値を使って床面積を計画してください。 部屋を大きくすると、間取りに必要な区画面積も変わります。配置後ではなく、境界を計算する際にこれらの数値を適用してください（composites のステップ0を参照）。
• 確認には必ず実際のカメラを使い、フリーカメラやエディターのビューポートは使わないでください。 ジオメトリの外側にも位置できるため、それらのビューでは屋内空間が実際より広く見えます。third_person でルートを歩き、そこからスクリーンショットを撮ってください（unity-explorer-mcp）。カメラが天井にめり込む場合や、アバターの頭が画面上端に迫る場合は、部屋の高さが足りません。

観察結果、同じセッション内： 最初に作られた、ほぼ現実的な高さの屋内空間（天井高4 m、出入口の高さ2.8 m、航空機の客室高2.2 m、搭乗橋高2.6 m）は、三人称視点では窮屈に見え、制作者は頭上の余裕を増やすよう求めました。有効幅0.75 mの金属探知機ゲートでは、アバターが通過できるようにするため、ほぼ完全な位置合わせが必要でした。

ルール：片面モデル — 描画面をプレイヤー側に向ける

多くの GLB モデルでは、裏面カリングが使われています。描画面は通常、ローカルの -Z 方向を向いています。Y 回転によって向きが変わります：0deg → 南、90deg → 東、180deg → 北、270deg → 西。プレイヤーが両側から近づく場合は、180deg 回転させたコピーをもう1つ追加してください。あらゆる角度から見える要素には、両面ジオメトリを優先してください。

Decentraland は Y-up の座標系を使用します。インポート後にモデルの向きを確認してください。Z-up でエクスポートされたモデル（Blender でよく使われます）は、傾いた状態で読み込まれるため、「Y Up」を指定して再エクスポートする必要があります。

ルール：テキストラベルは遮るもののない空間に置く — ジオメトリで隠さない

TextShape ラベルはワールド空間に描画されるため、ソリッドジオメトリに隠されることがあります。水平方向に2 m以内にソリッドモデルがない場所にラベルを配置し、高さ方向に十分な余裕を確保してください。読みやすいラベルには billboardMode: 2 の Billboard を使用し、開けた場所への設置を優先してください。例外は、Billboard なしで壁に取り付けるラベルです。

ルール：初期モデルには composite を使用する

シーンの読み込み時に存在するモデルは、TypeScript ではなく、必ず assets/scene/main.composite に追加してください。 TypeScript は、実行時に動的に生成するモデルにのみ使用してください。モデルに _collider メッシュがない（一般的なケース）場合は、visibleMeshesCollisionMask: 3, invisibleMeshesCollisionMask: 0 を使用してください。_collider メッシュがある場合は、visibleMeshesCollisionMask: 0, invisibleMeshesCollisionMask: 3 を使用してください。両方を同時にゼロ以外に設定してはいけません。

composite モデルに動作を追加するには、再作成せず、index.ts で名前またはタグを使って取得してください。

Creator Hub でシーンが開かれており、その MCP ツールを利用できる場合は、composite を編集するのではなく、ツールを使ってモデルを追加してください（スキル：creator-hub-mcp）。カタログアイテムには search_catalog + place_smart_item を使用してください（カタログには静的アイテムと Smart Items の両方が含まれており、ファイルも自動でダウンロードされます）。または、assets/Models/ に配置した GLB には、create_entity + set_component Transform + set_component core::GltfContainer を使用してください。どちらの方法でも、このスキルのバウンディングボックス、コライダーマスク、Animator のルールが適用されます。

ルール：モデルの src を差し替えるときは、新しい Transform を設定する — scale／position を引き継がない

既存の GltfContainer の src を変更するとき（composite 内、コード内、またはビルダーでのアセット置換）、そのエンティティの既存の Transform.scale、Transform.position、および多くの場合 rotation は、以前のモデル固有の寸法とピボットに合わせて調整されています。新しいモデルにはほぼ確実に適合しません。何も考えずに適用すると、建物がシーン境界を越えたり、小道具の高さが不適切になったり、モデルがユーザーの想定位置から目に見えてずれたりすることがあります。

モデルを差し替えるたびに、新規配置として扱ってください。

1. 新しい GLB の固有バウンディングボックスを調べます — {baseDir}/references/model-patterns.md のバウンディングボックススクリプトを使用してください（raw accessor の min／max だけでは不十分です。ノードレベルの scale／translation を適用する必要があります）。
2. scale を再計算し、ワールド空間でのサイズ（固有サイズ × scale）が用途に適したものになるようにします。以前のエンティティの scale は引き継がないでください。異なる固有サイズに合わせて調整されたものです。
3. ピボット位置を確認します。 建築物や建物の GLB の多くは、中心ではなく角（例：底面の一つの角が (0,0,0)）にピボットがあります。position が同じでもピボットが異なる 2 つのモデルを差し替えると、見た目の位置がずれます。
4. 結果のワールド空間バウンディングボックスがシーン境界内に収まることを確認します。 各区画の水平方向のサイズは 16 × 16 m です。区画数に関係なく、すべてのシーンで高さの上限は 330 m です（約 200 m を超える高さではマルチプレイヤー同期の問題が発生する可能性があります。{baseDir}/../optimize-scene/SKILL.md を参照してください）。position +/- bbox を使って、シーンの [0, maxX] × [0, maxZ] および y <= 330 の範囲内に収まるか計算してください。
5. 監査結果を明示します。 差し替え後、エージェントは新しい GLB の固有寸法、選択した scale、選択した position、シーン境界と照らし合わせた結果のワールド空間バウンディングボックスを報告する必要があります。以前の Transform を黙って使い続けてはいけません。

これは、コード内で Transform を変更せずに GltfContainer.createOrReplace(entity, { src: '...' }) を実行する場合も、core::GltfContainer.data["<id>"].json.src だけを変更する composite の編集にも同様に適用されます。

実行時の差し替え方法：モデルをその場で差し替えるには、フィールドを直接変更します — GltfContainer.getMutable(entity).src = newSrc — エンジンは同じエンティティ上で GLB を再読み込みします。GltfContainer の他のフィールド（例：visibleMeshesCollisionMask）も、同じ方法で実行中に変更できます。2 つのモデルの固有サイズとピボットが同じ場合に限り、Transform を再利用しても安全です。それ以外の場合は、上記の手順に従って改めて監査してください。

ルール：既存のコンポジットを編集する場合は、新しいエンティティをinspector::Nodesに登録する

このルールはファイルを手動で編集する場合に適用されます。手動編集は、Creator Hub MCPが利用できない場合に限ってください（詳細はcreator-hub-mcpを参照してください。create_entityを使えば登録も自動で行われます。また、Creator Hubでシーンを開いたまま手動編集すると、その編集内容は失われます）。

assets/scene/main.compositeにすでにinspector::Nodesが含まれている場合（ユーザーがCreator Hubでシーンを一度以上開いている場合）、追加する新しいエンティティはすべて、ここにも登録する必要があります。登録しないと、Creator Hubのエンティティツリーに表示されません。モデルはワールド内に表示されますが、ユーザーはエディターから選択・編集できません。新しいエンティティには、core-schema::Nameエントリーとinspector::TransformConfigエントリーも必要です。

追記する配列の正確な内容については、{baseDir}/../composites/composite-reference.mdの「既存のコンポジットを編集する（編集モード）」セクションを参照してください。既存のシーンに3Dモデルを追加する際は、必ずこの手順を行ってください。

ルール：モデルをプレイヤーに親子付けする場合は、アイテムの種類に応じて選ぶ

GltfContainerエンティティをプレイヤーに追従させる必要がある場合（手持ち武器、照準レティクル、装飾用バックパック、光輪、たいまつなど）、SDK7には3つの方法がありますが、これらは互換性がありません。照準に関係するアイテムのデフォルトは、engine.CameraEntityへの親子付けです。これはSDK6から移行する際に最もよくある間違いです。

• 照準に関係する手持ちアイテム（銃、照準レティクル、懐中電灯など、プレイヤーが見回すことで向きを変えられるアイテム） → Transform.create(entity, { parent: engine.CameraEntity, position: ..., ... })。カメラのヨーとピッチに追従するため、アイテムはプレイヤーの視線の先を向きます。これはSDK6のAttachable.FIRST_PERSON_CAMERAに相当するSDK7の方法です。ゲームプレイで使う手持ちアイテムには、これをデフォルトとして推奨します。
• ヨーのみ／身体に固定するアイテム（照準に使わない手持ちの盾、固定して持つたいまつ、照準しないインベントリアイテム） → Transform.create(entity, { parent: engine.PlayerEntity, position: ..., ... })。足元と身体のヨーのみに追従し、ピッチやアニメーションには追従しません。銃には不適切なデフォルトです。PlayerEntityに親子付けした武器は、プレイヤーが照準のために上を向いても水平のままです。
• 装飾アイテム（帽子、光輪、バックパック、ネームプレート、他のプレイヤーから見える装飾用のたいまつ） → AvatarAttach.create(entity, { anchorPointId: AAPT_HEAD | AAPT_SPINE | AAPT_LEFT_HAND | ... })。アニメーションするボーンに追従するため、アイテムは待機時の揺れ、歩行サイクル、ジェスチャーに合わせて視覚的に動きます。照準には使わないでください（アニメーションによる揺れで、照準に関係するアイテムは使い物になりません）。

銃にAAPT_RIGHT_HANDなどのボーンアンカーを使うと、「銃を手に持たせる」という点では正しく見えますが、手のボーンはアニメーションするため、銃は毎フレーム揺れて照準できません。これはSDK6のAttachable.FIRST_PERSON_CAMERAパターンから移行する際の落とし穴です。SDK7での正しい対応方法はengine.CameraEntityです。AvatarAttachでもengine.PlayerEntityでもありません（engine.PlayerEntityではピッチが反映されません）。

詳しい比較と、銃の具体例については[[player-avatar]]（手持ちアイテムと装飾アイテム）を参照してください。SDK6からの移行については、[[migrate-sdk6-to-sdk7]]を参照してください。

ルール：アニメーションを必ず確認する

GltfContainerを持つエンティティを確定する前に、GLBにアニメーションが含まれているか確認してください。アニメーションがある場合は、必ずAnimatorコンポーネントを追加してください。追加しないと、エンジンは最初のクリップを延々とループ再生します。アニメーションがない場合は、Animatorを省略してください。

ルール：組み込みコライダーを必ず確認する

GLBに_colliderメッシュが含まれているか（メッシュ名またはノード名に_colliderが含まれているか）を確認してください。{baseDir}/references/model-patterns.mdのコライダー検出スクリプトを使用してください。

正しいパターンは2つです。どちらか一方を選び、決して混在させないでください

モデルに _collider メッシュがある場合：visibleMeshesCollisionMask: 0, invisibleMeshesCollisionMask: 3

モデルに _collider メッシュがない場合：visibleMeshesCollisionMask: 3, invisibleMeshesCollisionMask: 0

役割に応じてマスクを選択してください。

役割	visibleMeshesCollisionMask	理由
インタラクティブ（クリック）	3	物理判定＋ポインター
構造物／装飾物	3	歩行とクリックをブロック
クリックのみ、かさのないもの	1	クリックのみを検出
純粋な装飾物	0	インタラクションなし

アンチパターン — 使用しないでください：visibleMeshesCollisionMask: 2, invisibleMeshesCollisionMask: 3 — 2つのパターンが混在し、ポインターの検出に失敗します。

ルール：エンティティの位置が常に区画の境界内にあることを検証してください

シーンの区画の完全に外側にあるエンティティはレンダリングされません — エラーは表示されません。境界をまたぐモデルは、内側にある部分がレンダリングされます。各区画は16x16 mです。有効な範囲：0 <= x <= 16 * parcelsWide、0 <= z <= 16 * parcelsDeep、y >= 0。

クリッピングが適用されるのはエンティティの位置ではなく、ジオメトリです。 Transform が有効な位置にあっても、区画の外にはみ出したジオメトリは保護されません。外側の部分は警告なしにクリップされ、モデルの残りの部分は表示されたままになります。そのため、完全に外側にベイクされたメッシュはまったく表示されなくなります。Bevy レンダラーでは Creator Hub の entitiesOutOfBoundaries は空のスタブなので、これによる検出を当てにしないでください。症状とプローブの手順については、上記のワールド座標のルールを参照してください。

TypeScript での3Dモデルの読み込み（動的エンティティのみ）

実行時に生成するエンティティには GltfContainer.create(entity, { src: 'assets/Models/myModel.glb' }) を使用してください。ファイルは assets/Models/ に配置します。

アセットフォルダーの規則

• モデルを自分でダウンロードする場合の標準パスは assets/Models/ です。
• レガシーシーンでは、モデルがすでに assets/scene/Models/ にある場合があります。このパスも引き続き使用できるため、これらのシーンにモデルを追加する場合は、新たに assets/Models/ フォルダーを作成せず、既存のパスを再利用してください。
• Creator Hub のアセット：Creator Hub の UI から直接インポートしたモデルは、標準パスと同じ assets/Models/ に配置されます。無料の DCL アセットパックのアイテムは assets/asset-packs/ に、カスタムアイテムは assets/custom/ に配置されます。古いシーンでは、ユーザーがインポートしたアイテムが assets/scene/ 直下にある場合もあります。これらのパスはそのまま参照してください。移動や名前の変更はしないでください。

新しいモデルの配置場所を決める前に、必ずシーン内の既存フォルダーを確認してください。

Creator Hub でシーンを開いている場合、「Local Assets」タブからビューポートにドラッグするのが最も手早い方法です。.glb／.gltf は、これまでどおり単体のモデルとしてドロップされます。creator-hub 062ed0a2 以降は、メディアファイルをドロップすると単体のコンポーネントではなく、カタログの Smart Items として配置されます。.png／.jpg／.jpeg は Material の PBR テクスチャ src が差し替えられた Image アイテムとして生成され、平面は地面に立つように +0.5 m 持ち上げられます。.mp3／.mp4 はそれぞれ対応するアイテムとして生成されます（audio-video を参照してください）。平面と Material を手動で組み立てる代わりに、平面画像をドラッグする方法を案内してください。完全なテーブルとアセット ID は creator-hub-mcp を参照してください。

ルール：新しいモデル — Blender でカタログとカスタム制作の両方を提案する

ユーザーからモデルの追加を依頼された場合、選択肢は 2 つあります。どちらを選ぶかはユーザーに委ね、決める前に尋ねてください。

「無料カタログ（すぐに使えるモデルが 8,800 点以上）から最適なものをダウンロードするか、Blender でカスタムモデルを作成できます。どちらがよいですか？」

• カタログ → 次のセクションのワークフロー（検索 → 確認 → ダウンロード）。
• Blender → Blender を操作してモデルを作成します。Blender の操作方法 2 通り、セットアップ、モデリングルール、エクスポートを網羅したガイドは {baseDir}/references/blender-authoring.md、すぐに使える bpy スクリプトは {baseDir}/references/blender-patterns.md にあります。Blender は、新しいモデルの作成だけでなく、既存のシーンモデルの編集（テクスチャの変更、形状の変更、最適化など）にも使用します。

サブエージェントとして実行している場合は質問できません。独断で選ぶのではなく、推奨案とともに選択肢を呼び出し元に伝えてください。

_アバター_のアニメーション（カスタムエモート）にも、同じ 2 通りの Blender 操作方法を使いますが、公式 Decentraland アバターリグと別のエクスポート手順を使用します。avatar-animations スキルを参照してください。このスキルの対象はモデルと小道具のみです。

Blender の操作方法 2 通り

	ヘッドレス CLI（blender --background --python）	Blender MCP
追加インストール	なし — Blender 本体のみ	Blender 5.1 以上、MCP アドオン、uv とサーバーパッケージ、クライアント登録、セッションの再起動
利用可能な場面	Blender がインストールされているすべてのセッション	セッション開始時に mcp__blender__* ツールがバインドされている場合のみ
操作モデル	バッチ処理：実行ごとに 1 つのスクリプトを使い、実行間で状態はリセットされます	ライブ操作：起動中の Blender で編集を重ね、状態は保持されます
視覚的な確認	一時的なカメラでレンダリングした静止画をディスクに保存	実際のビューポートのスクリーンショット
ユーザーの関与	結果のみ確認できます	開いている Blender GUI で作業を見ながら、共同編集もできます
最適な用途	形式変換、ポリゴン数の削減、バッチ最適化、スクリプトによるモデル構築	反復的なモデリングセッション、ユーザーが開いているファイルでの作業

ルール：ヘッドレスに切り替える場合は必ず事前に伝える

Blender でモデルを作成または編集するタスクで、MCP を使える可能性がある場合は、セッションの状態に応じて次の 3 つから選択してください。

1. MCP が接続され、動作している — 読み取り専用の確認（get_objects_summary など）が成功する → MCP を使用してください。 確認は不要です。

2. MCP は設定済みだが、接続されていない — セッションに mcp__blender__* ツールはあるものの、確認がエラーになる（Blender が起動していない、アドオンが無効になっている、ブリッジサーバーが停止しているなど） → ヘッドレスで進める前に必ず尋ねてください。

   「Blender MCP は設定されていますが、Blender が起動していません。Blender を開いてライブで作業しますか？モデルの作成過程を確認でき、一緒に編集することもできます。それとも、今回はヘッドレスで進めますか？」

   ユーザーは Blender を開くことをいとわず、モデルを一緒に作業したい場合もあります。ユーザーが希望した場合、または本当に尋ねられない場合（サブエージェントなど、完全に非対話の状況で、決めずに保留中の選択肢を呼び出し元に報告する場合）に限り、ヘッドレスに切り替えてください。

3. MCP がまったくインストールされていない — セッションに mcp__blender__* ツールがない → ユーザーにインストールを依頼しないでください（セットアップに大きな手間がかかります）。ヘッドレスで進めますが、ライブで対話的にモデルを編集する方法として Blender MCP があることと、セットアップ手順が {baseDir}/references/blender-authoring.md に記載されていることを報告に含めてください。

**理由：**モデルの作業を共同で進められるのは、MCP があるからです。ユーザーは自身の Blender セッションでモデルを見ながら、反復的に作業できます。ヘッドレスに黙って切り替えると、ユーザーに選択肢を与えず、この機会を奪うことになります。

どちらの方法を使っているか、必ず伝えてください。CLI で行った作業を MCP が行ったとユーザーに誤解させたり、その逆を招いたりしてはいけません。モデリングルール（ローポリ、PBR、パレットテクスチャ、コライダーの扱い、シーン制限）は、どちらの方法でも同じです。

無料の 3D モデル — OpenDCL カタログ（8,800 以上のモデル）

まず、シーンのローカルアセットフォルダーを必ず確認してください。モデルを取得する前に、必ずユーザーに確認してください。

カタログは {baseDir}/references/model-catalog.md にあります。grep -i "keyword" で検索してください。結果が見つからない場合は、類義語も試してください。grep "^##" でカテゴリを確認できます。

ワークフロー：カタログを検索 → 寸法／三角形の数／アニメーションを確認 → assets/Models/ に curl でダウンロード → コードで参照 → モデルにアニメーションがある場合は Animator を追加

重要：GltfContainer はローカルファイルでのみ動作します。必ず先に assets/Models/ にダウンロードしてください。モデルディレクトリに cd しないでください。プロジェクトのルートから curl を実行してください。

トラブルシューティング

問題	原因	解決方法
モデルが表示されない	ファイルパスが誤っている	プロジェクトルートからの相対パスを確認します
モデルが表示されない	シーンの境界の外にある	位置が各区画の 0～16 の範囲内にあるか確認します
モデルの一部が切れている	その部分が区画の外にある（境界でクリップされている）	モデルの境界がシーン内に収まるように、モデルを移動または拡大縮小します
モデルが表示されない	スケールが 0、または非常に小さい	Transform.scale を確認します
モデルは読み込まれるが、見た目がおかしい	Y-up と Z-up の不一致	Blender から「Y Up」で再エクスポートします
三角形はカウントされるが、どの視点からも表示されるレンダラーが 0 個	メッシュ全体が区画の外側にベイクされている（エンティティの位置は内側でもかまいません）	GLB の境界を DCL の軸で確認します。上記のワールド座標のルールを参照してください
"FINISHED_WITH_ERROR"	.glb が破損している	.glb（バイナリ GLTF）として再エクスポートします
クリックしても何も起きない	CL_POINTER が設定されていない	_collider メッシュがない場合は visibleMeshesCollisionMask: 3 を設定します
壁越しにクリックできる	CL_POINTER が可視メッシュに設定されていない	visibleMeshesCollisionMask: 3（または最低でも 1）を設定します
照明器具が照らさない	GLB のライト形状は見た目だけのものです	エンティティに LightSource コンポーネントを追加します（lighting-environment を参照）

ルール：3D モデルの照明器具は実際の光を放ちません

GLB 内のランプのメッシュ、電球の形状、シャンデリアのアーム、その他の照明器具の形状は、装飾のみのものであり、周囲のオブジェクトに動的な光を当てることはありません。Decentraland のレンダラーはこれらを通常の形状として扱います（任意で自己発光効果をもたらすエミッシブマテリアルを使用できます）。照明器具モデルで実際に照らすには、光源の位置に配置した同じエンティティまたは子エンティティに LightSource コンポーネントを追加してください。Creator Hub MCP が利用できる場合は、モデル、LightSource、切り替えアクションが一体になった Smart Item のライト（カテゴリ lights の Spotlight または Point Light など）を search_catalog で検索することをおすすめします。詳細は lighting-environment を参照してください。

モデルに関するベストプラクティス

• 読み込み時間を短くするため、各ファイルのモデルサイズは50MB未満にしてください。
• .glb 形式（バイナリ GLTF）を使用してください。.gltf よりサイズが小さくなります。
• 三角形の数を最適化してください。小さな小道具の場合、モデルあたり1,500個未満を目指してください。
• 可能であればテクスチャアトラスを使用し、ドローコールを減らしてください。
• 最良の結果を得るには、モデル内のマテリアルに PBR を使用してください。
• 繰り返し登場するコンテンツ（街灯、椅子、木など）では、複製ごとにほぼ同一のファイルを書き出すのではなく、多数のエンティティから共通の.glbを1つ参照してください。エンジンは、共有ソースのメッシュとテクスチャをセッション全体で一度だけダウンロード、変換、保存します。これによってドローコールやマテリアル数が減るわけではありません。どちらも描画されるオブジェクト数に応じて変わります。メッシュの結合が適切なケースについては、optimize-scene → Repeated Models を参照してください。
• ⚠️ シーンがモバイルを対象とする場合、Draco 圧縮は使用しないでください。 モバイルアプリにはランタイム Draco デコーダーがありません。Draco 圧縮された GLTF/GLB をスマートフォンで読み込めるのは、シーンの最適化済みアセットからの場合のみです（サーバー側で解凍されます）。最適化済みアセットがない場合、ローカルプレビューまたは Creator Hub のモバイルプレビューでは、どの環境でも読み込みに**失敗しますが、何も表示されません。モデルが表示されず、コンソールエラーもプレースホルダーも出ません。そのため、公開済みのシーンでは問題なく表示されるモデルが、すべてのモバイルプレビューでは見えないという状況になり、プレビューだけではほぼデバッグ不能になります。非圧縮で書き出し、代わりに三角形の数やテクスチャサイズを減らしてください。（ドキュメントのコミット 5f212e3、2026年10月。エラーダイアログは godot-explorer #2432 で追跡中です。以下のエンジンシーン 54,-55-Testing-3d-models には Draco 版が含まれていますが、これはデスクトップの機能テスト用であり、クロスプラットフォームでの推奨ではありません。）

コードの完全な例（読み込み、コライダー、操作、カタログのワークフロー）については、{baseDir}/references/model-patterns.md を参照してください。アセットカタログ（8,800以上のモデル）については、{baseDir}/references/model-catalog.md を参照してください。

シーンの例

実際のランタイムでこれらの API をテストする、エンジンチームのテストシーンです。

• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/54,-55-Testing-3d-models — GltfContainer を使用して読み込む多数の GLB バリエーション（Draco、モーフターゲット、リグ付きアニメーション、外部依存モデル）。assets/Models/ ではなく、models/ フォルダーを使用している点に注意してください。
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/3,33-gltf-container-update — GltfContainer.getMutable() を使用して、読み込み済みモデルの src を切り替え、visibleMeshesCollisionMask を変更します（クリックすると Book と Monster が切り替わり、CL_CUSTOM1 に対してレイキャストします）。
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/88,-12-asset-load — AssetLoad コンポーネントとアセットごとの読み込み状態コールバックを使用して、GLB、音声、テクスチャ、動画を事前読み込みします。また、クリック時に GltfContainer.getOrCreateMutable() でモデルを遅延スポーンします。