deploy-scene

Genesis City へのデプロイ

Creator Hub エージェントにはインストールされません。 Creator Hub のスキルインストーラーはこのスキルを拒否リストに登録しており、ディレクトリには SKILL.md しか含まれていないため、完全にスキップされます。そのため、アプリに組み込まれた AI アシスタントには届きません。公開は Creator Hub 独自の UI から行います。Creator Hub のアシスタントとして、ユーザーから公開を依頼された場合は、アプリの「公開」フローを案内してください。Creator Hub の外部（Claude Code、Cursor、SDK エージェント）では、このスキルは通常どおり動作します。

所有している、またはデプロイ許可を得ている特定の区画にデプロイします。

デプロイには /deploy コマンドを使用します。 このコマンドは npx @dcl/sdk-commands deploy を実行し、以下の全工程を処理します。

1. シーンをビルドする
2. アセットを IPFS にアップロードする
3. 指定した区画にデプロイする
4. LAND またはデプロイ権限を持つウォレットが必要です

代わりに World にデプロイしますか？ World のデプロイについては、deploy-worlds スキルを参照してください（DCL NAME または ENS ドメインを使用する個人用スペース）。

デプロイ前のチェックリスト

デプロイする前に、以下を確認してください。

1. scene.json が有効であること：

   • ecs7: true および runtimeVersion: "7"
   • LAND に合った parcels（Genesis City の場合）
   • 有効な base パーセル
   • main: "bin/index.js"

2. ディスカバリーメタデータが揃っていること — シーンを見つけて入ってもらえるかどうかは、この4つのフィールドで決まります。テンプレートの初期値のままになっていることもよくあります。各フィールドを確認し、シーン自体から推測できる内容を入力してください。推測できない内容のみユーザーに尋ねてください。

   • display.title — シーン名。ゲーム内ではミニマップの下に、マップモーダルにも表示されます
   • display.description — シーンの内容を説明する1〜2文
   • tags — ルートレベルの配列。定義済みリストから Places dApp のカテゴリを1〜3個指定します：「"art"」、「"game"」、「"casino"」、「"social"」、「"music"」、「"fashion"」、「"crypto"」、「"education"」、「"shop"」、「"business"」、「"sports"」、「"parkour"」。シーンのテーマから推測してください（create-scene スキルの「Tags (scene categories)」を参照）
   • display.navmapThumbnail — 設定するだけでなく、画像自体も有効であることを確認してください。参照先のファイルがプロジェクト内に存在する（またはURLにアクセスできる）こと、画像サイズが16:9（1920x1080を推奨）であること、重要なコンテンツが中央の1080x1080の正方形内に収まっていることを確認します。シェルでサイズを確認します。macOS では sips -g pixelWidth -g pixelHeight <path>、または magick identify -format "%wx%h\n" <path> を実行し、中央の正方形に切り抜いて全体ではなく切り抜いた画像を確認してください。テキストと被写体はすべて正方形内に収めてください。macOS の場合：H=$(sips -g pixelHeight <path> | awk '/pixelHeight/{print $2}'); sips -c $H $H <path> --out "${TMPDIR:-/tmp}/thumb-square.png"。ImageMagick の場合：H=$(magick identify -format %h <path>); magick <path> -gravity center -crop ${H}x${H}+0+0 +repage "${TMPDIR:-/tmp}/thumb-square.png"。その後、正方形の画像を読み込んで確認してください。画像がない、縦横比が正しくない、または被写体が片側に寄っている場合は、再度キャプチャしてください。詳しくは以下の Thumbnail image を参照してください

3. コードがコンパイルできること：

   npx tsc --noEmit
   

4. シーンが正しくプレビューできること： preview ツールを使ってシーンが動作することを確認してください（または npx @dcl/sdk-commands start を手動で実行してください。必要に応じて --web を追加すると、Bevy Web ブラウザークライアントでプレビューできます）。複数のブラウザータブでテストし、マルチプレイヤーの動作を確認してください。

5. 依存関係がインストールされていること：

   npm install
   

6. アセットが制限内に収まっていること — パーセル数ごとの制限の計算式（ポリゴン数、エンティティ、マテリアル、テクスチャ）と、一律330 mの高さ制限については、optimize-scene スキルを参照してください。アセットを最適化し、シーンの読み込み時間を15秒未満にしてください。

   そのうえで、却下された後ではなく、デプロイ前に実際にアップロードされるデータのサイズを確認してください。

   find assets -type f -size +1M -exec ls -lh {} +        # the heavy files
   npx @gltf-transform/cli inspect assets/Models/big.glb   # Textures table: each embedded map's resolution and bytes
   

   埋め込み型の2048 pxテクスチャマップは、よく見落とされる要因です。生成された2つのGLBに合計17 MBのテクスチャが含まれ、34 MBのシーンになっていたことが公開後に初めて判明した事例があります（エージェント報告、2026-10）。1024以下にリサイズしてください（npx @gltf-transform/cli resize in.glb out.glb --width 1024 --height 1024 または Blender を使用。optimize-scene を参照）。コンバーターはどのみち1024に縮小しますが、元ファイルのサイズはそのまま全量がカウントされます。プロジェクト内の bin/index.js からサイズを推測しないでください。プレビューの開発ビルドにはインラインのソースマップが含まれ、ミニファイされていません。一方、deploy は --production を指定して再ビルドします（ミニファイ済み、ソースマップなし — @dcl/sdk-commands の commands/deploy/index.ts）。通常、サイズはその一部になります。

7. .dclignore にすべての作業ファイルが含まれていること — Blender/FBX のソース、コンセプトアート、スプレッドシート、Markdown ドキュメントなどをアップロードしてはいけません。以下の .dclignore セクションを参照してください。

デプロイ手順

CLI を使用する

# Build first
npx @dcl/sdk-commands build

# Deploy (will open browser for wallet connection)
npx @dcl/sdk-commands deploy

Creator Hub を使用する

1. Creator Hub を開きます
2. シーンを選択します
3. 「Publish」をクリックします
4. ウォレットを接続します
5. トランザクションを確定します

公開後に共有するリンク

成功パネルには、デスクトップクライアントを持たないプレイヤーでも利用できる ウェブ版の /jump リンク が表示され、コピーできます。「Jump In」 ボタンを押すと、別途デスクトップクライアントが開きます（creator-hub 4305bb17c）。プレイヤー向けに記述する際は、次の形式を使用してください。

対象	共有リンク
Genesis City のシーン	https://decentraland.org/jump?position=x,y
ワールド	https://decentraland.org/jump?realm=NAME.dcl.eth
デスクトップクライアントを直接開く	decentraland://?position=x,y&dclenv=<env>（または ?realm=…）

/jump が正式な形式です。従来の /play/... パスは /jump に 301 リダイレクトするだけなので、生成しないでください。

デプロイ用の scene.json

{
  "ecs7": true,
  "runtimeVersion": "7",
  "display": {
    "title": "My Awesome Scene",
    "description": "A description for the marketplace",
    "navmapThumbnail": "images/thumbnail.png"
  },
  "tags": ["art", "social"],
  "scene": {
    "parcels": ["0,0", "0,1"],
    "base": "0,0"
  },
  "main": "bin/index.js"
}

tags はルートレベルに配置し、display の下には置きません。有効なカテゴリ値については、上のチェックリスト項目を参照してください。

サムネイル画像

display.navmapThumbnail は、プレイヤーがシーンの区画を選択したときにマップモーダルに表示される画像です。また、別のシーンからプレイヤーがテレポートしてきたときに確認画面にも表示されます。必ず指定してください。

仕様：

• .png または .jpg、アスペクト比は 16:9、推奨サイズは 1920x1080 px です。16:9 であれば他のサイズでも使用できます。それ以外のサイズは引き伸ばされます
• 中央の正方形のセーフエリア： プラットフォームによっては、中央の 1080x1080 px を正方形に切り抜いて表示します。テキスト、ロゴ、メインの被写体はこの範囲内に収めてください。1920x1080 の画像では、左右の 420 px の帯が切り落とされることがあります
• 1 MB（1,048,576 bytes）未満： これを超える画像は、デプロイ時に Worlds コンテンツサーバーによって拒否されます（Invalid thumbnail: size … exceeds maximum of 1048576 bytes (1MB)）。通常の 1920x1080 PNG はこの上限を超えることがあります。公開前に ls -l で確認してください。超えている場合は、代わりに JPEG としてエクスポートします（ffmpeg -i images/thumbnail.png -q:v 2 images/thumbnail.jpg）。撮影ではなく生成したカバー画像（Blender のレンダーや画像ツールなど）については、creator-hub-mcp > Gotchas を参照してください
• 値には、プロジェクト内のパス（例：images/thumbnail.png）または外部ホスト上の画像 URL を指定します。外部ホストでは、制限の緩い CORS ヘッダーを返す必要があります

自分で撮影する — 画像を提供する代わりにこちらで撮影することを希望するか、ユーザーに確認してください。 unity-explorer MCP（unity-explorer-mcp スキルを参照）を使い、シーンをプレビューで実行します。カメラを動かしてシーンの内容が伝わる構図にし、重要なコンテンツが中央の 3 分の 1、かつ中央の正方形内に収まるようにして、同梱スクリプトで UI のない PNG を撮影します。

# <skill-dir> is the unity-explorer-mcp skill's base directory
<skill-dir>/scripts/screenshot.sh --world-only --png -w 1920 -o images/thumbnail.png

クライアントウィンドウを 16:9 で起動すると（npm run start -- --mcp -- --windowed-mode --resolution 1920x1080）、フレームもネイティブで 16:9 になるため、切り抜きは不要です。それ以外の場合は、次の方法でサイズを調整します。

# ImageMagick: center-crop to 16:9 and resize, in one step
magick images/thumbnail.png -resize 1920x1080^ -gravity center -extent 1920x1080 images/thumbnail.png

# macOS, no extra tooling: -c takes HEIGHT then WIDTH, both centered
sips -g pixelWidth -g pixelHeight images/thumbnail.png   # read the source size first
sips -c 1080 1920 images/thumbnail.png --out images/thumbnail.png   # center-crop a larger frame
sips -z 1080 1920 images/thumbnail.png                              # then resample to exactly 1920x1080

生成したパスを display.navmapThumbnail に指定してください。MCP を利用できない場合に限り、画像なしでシーンを公開するのではなく、ユーザーに画像を依頼してください。.dclignore でサムネイルが除外されていないことを確認してください。シーンと一緒にアップロードする必要があります。

大文字と小文字は区別されます。 navmapThumbnail のパスは、ディスク上のフォルダー名と完全に一致させる必要があります。デプロイ対象のファイル一覧ではディスク上の大文字・小文字が保持され、Catalyst は大文字・小文字を区別します。一方、macOS と Windows ではローカルでどちらの表記でも解決されるため、不一致があっても気づきにくく、公開すると Scene thumbnail '…' must be a file included in the deployment というエラーが発生し、テストにも表示されません。Creator Hub プロジェクトの標準フォルダーは assets/Images/（I は大文字）で、Hub が自動生成したキャプチャもここに書き込みます。パスを指定する前に ls assets を実行し、大文字・小文字だけが異なるフォルダーを 2 つ作らないでください。

スポーンポイント

シーンに入ったときにプレイヤーが出現する場所を設定します。

{
  "spawnPoints": [
    {
      "name": "spawn1",
      "default": true,
      "position": { "x": [1, 5], "y": [0, 0], "z": [2, 4] },
      "cameraTarget": { "x": 8, "y": 1, "z": 8 }
    }
  ]
}

位置の範囲（例：[1, 5]）を指定すると、プレイヤーは範囲内のランダムな位置にスポーンします。スポーン時のプレイヤーのカメラの向きは、cameraTarget で設定します。

.dclignore — アップロード対象からファイルを除外する

.dclignore ファイルは常にプロジェクトのルートに置き、デプロイ時にコンテンツサーバーへアップロードしないファイルやパターンを指定します。.dclignore に一致しないプロジェクトフォルダー内のファイルはすべてアップロードされ、その合計サイズはパーセルごとの MB 上限に含まれます。そのため、実行中のシーンが実際に必要とするファイルだけをデプロイしてください。

形式：1 行につき 1 つの glob パターンです。シーンテンプレートのデフォルト設定：

.*
package-lock.json
yarn-lock.json
build.json
export
tsconfig.json
tslint.json
node_modules
*.ts
*.tsx
.vscode
Dockerfile
dist
README.md
*.blend
*.fbx
*.zip
*.rar
*.md
src

プロジェクトの成長に合わせて最新の状態に保ってください。 プロジェクト内に作業ファイルが存在する場合は、Blender などの 3D ソースファイル、ドラフトモデル、コンセプトアート、PSD、スプレッドシート、Markdown のメモ、参考写真などを、.dclignore に追加してください（または、ファイルの拡張子を追加してください）。デプロイするシーンをできる限り軽量に保てます。シーンを作成または編集するときは、デプロイが失敗するまで待たず、事前にこれらのパターンを追加してください。よく追加されるパターン：

*.blend
*.blend1
*.fbx
*.psd
*.kra
*.xcf
*.md
*.csv
*.xlsx
drafts
concept-art
reference

デプロイが 「Scene is too large」 というエラーで失敗した場合は、最初に .dclignore を確認してください。超過分の大半は作業ファイルであることが多く、それらを除外すればシーンに影響を与えずにアップロードサイズを削減できます。

実行時にシーンが必要とするファイルは、絶対に除外しないでください。 bin/index.js、scene.json、assets/（コンポジット、.glb モデル、テクスチャ、サウンド、動画）、scene.json で参照されているサムネイル、またはコード内で参照されているファイルパスが該当します。デフォルト設定では *.ts／src が除外されている点に注意してください。実行されるのはコンパイル済みの bin/index.js のみなので、ソースコードはアップロードに必要ありません。

公開後：アセットバンドルへの変換

公開するたびに、コンテンツサーバーはすべての .gltf／.glb モデルをアセットバンドル（大幅に軽量な形式）に圧縮します。変換はすぐに開始されますが、プラットフォーム（Windows、Mac）ごとにキューに登録されます。変換中、プレイヤーには意図的に最後に正常に動作していたバージョンのシーンが配信されます。

• 通常の所要時間： 数秒です。 非常に大きなシーンの場合や、変換サーバーが混雑している場合は、さらに時間がかかります。（以前のドキュメントにあった約 15 分／30〜60 分という記載は、ドキュメントのコミット 2dfbb00 で修正されました。）
• 変換が数分以上続いている場合は、通常のキュー待ちではなく、失敗の兆候です。 待ち続けるのではなく、ステータスエンドポイントを確認してください。
• アップロードと変換が完了し、シーンをプレイできるようになると、Jump In ボタンが表示されます。
• ライブイベントの前には： 予期しない問題に備えるため、最終バージョンを少なくとも 1 時間前に公開してください。待機中に再公開するのは避けてください。公開のたびにキューが再開します。
• **変換ステータスを確認するには、**ブラウザーで次の URL を開きます。
  • https://asset-bundle-registry.decentraland.org/entities/status/<pointer> — <pointer> をシーン座標（例：20,-34）またはデプロイエンティティ ID に置き換えてください。assetBundles にプラットフォームごとのステータスが、lods に LOD ステータスが表示されます。World の場合は、?world_name=myname.dcl.eth を追加してください。
  • https://asset-bundle-registry.decentraland.org/queues/status — 現在変換キューに登録されているすべてのシーンが、プラットフォームごとに一覧表示されます。
• /detectabs チャットコマンド： ワールド内でモデルを緑色（変換済み）または赤色（未変換）に色付けします。
• **シーンを再読み込みするだけでは、新しいバージョンは反映されません。**再読み込みするとシーンのコードは再起動しますが、新たに公開されたコンテンツは取得されません。このセッションですでにシーンを読み込んだプレイヤーには、Decentraland を完全に終了して再起動するまで、キャッシュされたバージョンが表示され続けます。 あなたも同様です。変換が完了したら、いったん終了して再起動し、ジャンプリンクまたは /goto から再度入場してください。

プレビューでローカルアセットバンドルを有効にすれば、公開前に変換の問題を確認することもできます。optimize-scene スキルの「Local Asset Bundle Preview」を参照してください。

トラブルシューティング

エラー	原因	解決策
"You don't have permission to deploy"	ウォレットが対象のLAND／区画を所有していません	マーケットプレイスでLANDの所有権を確認するか、LAND所有者からデプロイ権限を取得してください
"Scene is too large"	アセットが区画のサイズ制限を超えています	まず、作業ファイル（Blender／FBXのソース、コンセプトアート、ドキュメント）をすべて .dclignore に追加してください。上記の .dclignore セクションを参照してください。その後、三角形の数、ファイルサイズ、テクスチャ数が制限内か確認してください。optimize-scene スキルを参照してください
Wallet connection fails	ブラウザーのポップアップがブロックされているか、MetaMaskがロックされています	ポップアップを許可し、MetaMaskのロックを解除して、ページを更新してからもう一度お試しください
"Invalid scene.json"	必須フィールドがないか、JSONの形式が正しくありません	ecs7: true、runtimeVersion: "7"、有効な parcels 配列、main: "bin/index.js" を確認してください
Deploy succeeds but scene is empty	main フィールドがコンパイル済みの出力を指していません	main が "bin/index.js" になっていることを確認し、先に npx @dcl/sdk-commands build を実行してください
Catalyst rejection	コンテンツがDecentralandのコンテンツポリシーに違反しています	docs.decentraland.org でコンテンツガイドラインを確認してください
Scene looks broken right after deploy	アセットバンドルの変換がまだ完了していません	チャットで /detectabs と入力してください。赤みがかったモデルはまだ変換されていません。変換状況（上記参照）を確認し、完了するまでお待ちください
Some players see old version, others see new	プラットフォームごとに変換の完了時刻が異なり、クライアントのキャッシュも影響します	変換状況エンドポイントの assetBundles で windows と mac の両方を確認してください。両方が complete になったら、影響を受けているプレイヤーはDecentralandを完全に再起動する必要があります
Publication stuck on Converting stage	変換に失敗したか、シーンがほかのシーンの後ろでキューに入っています	通常、変換には数秒しかかからないため、数分を超える場合はキューではなく失敗の可能性があります。エンティティIDのキュー状況URLを確認してください。キューに入っていない場合は変換状況を確認し、プラットフォームに failed と表示されていたら再公開してください。再度失敗する場合は、エンティティIDを添えてバグを報告してください
3D models missing, black, or untextured after deploy	変換がまだ進行中か、テクスチャが変換上限を超えています	/detectabs で確認してください。変換中、3Dモデルのテクスチャは 1024x1024 が上限です（512x512ではありません。この数値は古い情報です）
Scene looks fine up close but broken from a distance	LODの生成（公開の最終段階）がまだ完了していません	変換状況エンドポイントの lods の値を確認してください。LODは近距離でのテストを妨げません
"Scene thumbnail '…' must be a file included in the deployment" (the file plainly exists)	display.navmapThumbnail とディスク上のフォルダーの大文字・小文字が一致していません。通常、scene.jsonでは assets/images/ となっているのに、ディスク上では assets/Images/ になっています	アップロードされたファイル一覧ではディスク上の大文字・小文字が保持され、Catalystは大文字・小文字を区別して照合します。一方、macOS／Windowsではどちらの表記でもローカルで解決されるため、この問題はデプロイ時にのみ発生します。ls assets で実際のフォルダー名を確認し、navmapThumbnail の表記を完全に一致させてください。標準はアセットインポーターが作成する assets/Images/（Iは大文字）です。大文字・小文字だけが異なるフォルダーを2つ作らないでください
"Invalid thumbnail: size … exceeds maximum of 1048576 bytes"	サムネイルが1 MBを超えています（通常の1920x1080 PNGでも超えます）	高画質のJPEGとしてエクスポートする（ffmpeg -i cover.png -q:v 2 cover.jpg）か、1344x756に縮小してください。チェックはデプロイ時にサーバー側で行われるため、ローカルでは警告されません。また、縦横比は16:9から1%以内である必要があります

Genesis City と Worlds

	Genesis City	Worlds
要件	LAND の区画を所有する	DCL NAME または ENS ドメインを所有する
区画の制限	適用されます（区画ごとのエンティティ／三角形の予算）	LAND による制約はありません
表示	Genesis City のマップに表示されます	Places ページに表示されます（非表示に設定できます）
デプロイ先	デフォルトの Catalyst ネットワーク	--target-content https://worlds-content-server.decentraland.org
最適な用途	常設インストール、トラフィックの多いシーン	テスト、個人スペース、イベント

World にデプロイする場合：deploy-worlds スキルをご覧ください。

シーンへのチップ

訪問者がシーンのクリエイターに MANA チップを送れるようにします。scene.json に creator フィールドを追加します。

{
  "creator": "0x1234567890123456789012345678901234567890"
}

設定すると、訪問者には左上に貯金箱アイコンが表示されます。クリックすると MANA チップのモーダルが開きます。アドレスが Decentraland NAME にリンクされている場合、モーダルに名前が表示されます。クリエイターにはチップを受け取るたびにアプリ内通知が届きます。

Creator Hub → シーンの Settings → Details → Creator wallet address からも設定できます。