sdk-scenes

Decentraland SDK7 シーン開発

ランタイムの制約： Decentraland は QuickJS サンドボックスで実行されます。Node.js API（fs、http、path、process）は使用できません。非同期処理には executeTask() と fetch() を使用してください。

エージェントの行動ガイドライン

重要な操作を行う前に、それが以下のいずれかに該当するか確認し、必ず事前にユーザーに確認してください。

質問の仕方： 基盤となるコマンドではなく、_シーンに何が起こるか_を説明する、平易で専門用語を使わない言葉で質問してください。

よい例：「この木のモデルをシーンのアセットにダウンロードしてもよいですか？」 悪い例：「curl https://… -o assets/Models/tree.glb を実行しますか？」

1. 区画数またはレイアウトの変更

scene.json の scene.parcels を変更すると、シーンの座標空間が変わります。現在の境界付近にあるエンティティが範囲外（非表示）になったり、誤った区画内に入ったりする可能性があります。また、ユーザーがデプロイ先のスロットを想定している場合があり、区画数をそれに合わせる必要があります。操作する前に、変更内容とその影響を説明してください。

「ご説明いただいたシーンを実現するには、1 区画（16×16 m）から 2×1 のレイアウト（32×16 m）に拡張する必要があります。これにより、すべてのエンティティの座標範囲が変わります。進めてもよいですか？」

ルールは変更を避けることではなく、尋ねることです。区画で確保できる範囲より広いスペースが必要なデザインの場合は、ユーザーに確認してください。黙って区画を追加したり、質問を避けるためにデザインを縮小したりしないでください。（2026-10：あるエージェントは、尋ねずに1区画内で脱出ルームを3つ縦に積み重ねました。オーナーのコメント：「どうして、区画をもっと割り当てる必要があると気づかなかったの？」）

2. 外部ソースからのアセット取得

プロジェクトにまだないファイル（3D モデル（.glb）、画像、音声、動画）をダウンロードする場合です。ユーザーには使いたいアセットがあるかもしれませんし、新しいファイルの追加を望んでいない場合や、特定のビジュアルスタイルを目指している場合もあります。ダウンロードする前に確認してください。

「[source] から [description] のモデルをダウンロードして、シーンに追加したいと考えています。進めてもよいですか？」

ストリーミング参照（AudioStream、VideoPlayer）の場合：ファイルはダウンロードしませんが、外部 URL への依存関係が追加されます。URL がユーザーから提示されていない場合は確認してください。

「[source] からの動画ストリームを設定しようと思います。こちらを使いますか？」

3. マルチプレイヤーサーバーの追加

isServer()、registerMessages()、Storage、EnvVar の導入、または @dcl/sdk@auth-server への切り替えが必要になります。この機能を使うには、別の SDK ブランチ（@dcl/sdk@auth-server）に切り替える必要があります。「マルチプレイヤー」を望むユーザーの多くは、よりシンプルな multiplayer-sync スキル（サーバー不要）だけで十分です。実装する前に確認してください。

「この方法でマルチプレイヤーに対応するには、マルチプレイヤーサーバーを追加する必要があります。そのため、標準の SDK ではなく @dcl/sdk@auth-server SDK ブランチに切り替えることになります。こちらをご希望ですか？それとも、用途にはよりシンプルなピアツーピア同期で十分でしょうか？」

4. Blender MCP からヘッドレス Blender への切り替え

セッションに mcp__blender__* ツールが存在するものの、接続されていない（Blender が起動していない、またはアドオンが無効になっている）場合は、決して黙ってヘッドレス Blender CLI に切り替えないでください。まず確認してください。

「Blender MCP は設定されていますが、Blender が起動していません。Blender を開いて、モデルの作成をリアルタイムで進めましょうか。作成中のモデルを確認しながら、一緒に編集できます。それとも、ヘッドレスで作業しましょうか？」

モデル制作を共同作業にするのが MCP の役割です。黙って切り替えると、その選択肢を奪うことになります。MCP がまったくインストールされていない場合は、インストールをユーザーに求めないでください。ヘッドレスで作業し、報告時に MCP を選択肢として簡単に伝えてください。詳しいルールは add-3d-models を参照してください。

5. Creator Hub でシーンが開いている場合に、コードで静的ジオメトリを構築する

壁、床、家具、小道具をシーンに追加する必要があり、Creator Hub MCP がセッションにない（mcp__creator-hub__* ツールがない）うえに、シーンがCreator Hub で開いている、または開いている可能性がある場合は、作業を止め、ユーザーに選択してもらってください。自分の判断で src/ 内の engine.addEntity() に切り替えてはいけません。シーンが開いている、または Hub が管理していることを示す兆候は次のとおりです。

• pgrep -fl 'sdk-commands start' に、シーンフォルダーをパスに含む sdk-commands start … --data-layer が表示される場合。これは強い兆候です。シーンフォルダーに対する tsc … --watch は手がかりにすぎません（通常のプレビューでも実行されます）。
• .editor/project.json が存在する、または assets/scene/main.composite に inspector::* コンポーネントが含まれる場合。Hub が少なくとも一度はシーンを開いています。

次のように尋ねてください。

「シーンが Creator Hub で開いているため、シーンファイルに安全に部屋を追加できません。エディターが変更を上書きしてしまうからです。進め方は3つあります。（1）Creator Hub でシーンを閉じてもらえれば、シーンファイルにすべて追加します。（2）Settings > AI > Expose AI assistant MCP server をオンにして接続してもらえれば、エディター上でリアルタイムにすべて配置します。（3）コードで部屋を構築します。プレビューには表示されますが、エディターには表示されないため、そこで選択したり移動したりすることはできません。どれがよいですか？」

選択肢3が許されるのは、ユーザーが明示的に選んだ場合に限ります。その判断なしに src/ で静的エンティティを構築することは、グレーボックス、プロトタイプ、「一時的な」代替物であっても、セッションが非対話型または自律型であっても、決して許されません（質問を最終メッセージに記載してください）。まず、回答に依存しない作業（スクリプト、動作、アセットファイル）をすべて行い、その後は質問をして停止してください。（2026-10-23：エージェントは開いているシーンのコンポジットを手作業で編集することを拒んだ後、コードで部屋全体、椅子1脚、小道具約60個を構築し、要約で初めてそのことに触れました。作成者のコメント：「警告なしにこれを行うのは絶対にやめてください……ユーザーがどうするかを決めます。」）これが基準となる記述です。composites と creator-hub-mcp はここを参照してください。

6. SDK の回避策を講じる前にバグを報告する

SDK、Explorer、または Creator Hub がドキュメントどおりに動作しない、あるいはシーンに必要な機能がない場合に、回避策を講じようとしているなら、まず report-sdk-issue スキルを使って報告してください。シーンでこれが初めて発生したときは、SDK の問題報告を送信してよいかユーザーに尋ねてください。その後は、回答に応じて、確認せずに報告するか、報告しないようにしてください。報告を送信した際は、その旨を1行でユーザーに伝えてください。報告によって作業が止まることはありません。

プラットフォームの制限と判断する前に、次の順で確認してください。担当トピックのスキル、node_modules/@dcl/ecs 内のインストール済み型定義、最小限の再現例、実行中のクライアントと SDK のバージョン、そして実行中のバージョンに対応する Explorer と SDK の変更履歴に記載された既知の修正です。古いソースのチェックアウトは、目の前のクライアントについて何も証明しません（あるセッションでは、修正がすでにリリースされた後に、8月のチェックアウトを根拠に音量フェードを使えないと判断しました）。アーキテクチャ上の回避策を考案する前に、シーンのエラー、エンジンの不具合、未対応機能を区別してください。APIを思い出せないことは、そのAPIが存在しない証拠にはなりません（advanced-rendering の GltfNodeModifiers は実行時に GLB マテリアルを変更します。数字キーのアクションは advanced-input の IA_ACTION_3～IA_ACTION_6 です。メンバーを推測せず、列挙型を確認してください）。

7. ランタイムビューなしで作業する

explorer MCP サーバーが接続されていない場合（ConnectionRefused、または explorer_* / mcp__explorer__* ツールがない場合）は、その旨を一度伝え、unity-explorer-mcp に従ってセットアップすることを提案してください。接続が拒否されるのは、Explorer が起動していないという意味にすぎません。それまでは、視覚的な主張にはすべて未検証であることを明記し（「ベゼルに収まるはずですが、まだ確認できていません」）、コードだけを根拠に視覚的な修正が完了したと報告してはいけません。2026-10 に同じシーンで行われた2回のセッションでは、この方法により、すべての視覚的な不具合がオーナーに引き継がれました。

Explorer MCP が接続されている場合は、変更を完了したと報告する前に、必ずゲーム内で検証してください。ユーザーに頼まれるまで待ってはいけません。検証できるのに「ゲーム内では未検証」のままでは、完了したことになりません。MCP が以前セットアップされていても Explorer が起動していない場合は、unity-explorer-mcp の手順を経て起動することを提案してください。頼まれていないのに起動してはいけません。

一般原則

これらはエージェントが拒否すべきことではなく、実行する前に説明すべきことです。ユーザーが承認したら、確信を持って進めてください。目的は透明性であり、行動を妨げることではありません。

---

重大なルール — コンポジットを優先したシーン作成

すべての静的エンティティ（モデル、プリミティブの壁や床、ライト、スポーン地点）は、TypeScript で engine.addEntity() を使って作成するのではなく、assets/scene/main.composite で定義する必要があります。Creator Hub で開いているシーンにエンティティを配置するには、MCP（creator-hub-mcp）を使います。src/ に作成した部屋はプレビューではレンダリングされますが、エディターでは見えません。シーンが開いていて MCP を利用できない場合は、作業を中断してユーザーに確認してください（シーンを閉じる／MCP を接続する／コードでエンティティを作成することを明示的に承認する）。独断で静的エンティティを src/ に作成してはいけません（エージェント行動ガイドライン、項目5）。

TypeScript（src/index.ts）は、以下の用途にのみ使用します。

• 動的な動作（システム、イベントハンドラー、状態の変更）
• getEntityOrNullByName('name') または getEntitiesByTag('tag') を使ったコンポジットエンティティの参照
• 実行時にのみ存在するエンティティ（ゲームプレイ中に生成／破棄されるもの）

重大なルール — 既存のコンポジットの編集

Creator Hub MCP が利用できる場合は、それを使ってください。ファイルを手動で編集してはいけません。 Creator Hub には MCP サーバー（スキル：creator-hub-mcp）が組み込まれており、そのツール（scene_state、create_entity、set_component、remove_entity、place_smart_item、attach_script、set_scene_settings、…）を使うと、オートセーブ、元に戻す操作、エディターの管理情報を処理しながら、開いているシーンをリアルタイムで編集できます。Creator Hub 自身の AI アシスタントにはあらかじめ接続されており、ほかの MCP 対応ツール（Claude Code、Cursor、Codex、Claude Desktop）も、Settings > AI > Expose AI assistant MCP server から接続できます。scene.json の変更にもこれを使ってください（set_scene_settings）。シーンを Creator Hub で開いたままファイルを編集すると、作業が気付かないうちに失われます。インスペクターはデフォルトでオートセーブし、メモリー上のエンジンから main.composite 全体を再生成してファイルを丸ごと上書きするためです。ディスクからファイルを読み直すことはありません。

MCP が利用できない場合（Creator Hub が関与していない、またはユーザーが接続を断った場合）に限り、assets/scene/main.composite を直接編集してください。その場合は、以下の点に従ってください。

• ファイルを編集している間、シーンを Creator Hub で開いていてはいけません。 まずシーンを閉じるようユーザーに依頼し、作業が完了したら再度開いてもらってください。返答があるまでは、ファイルにも、代替手段としての src/ にも、静的なものを一切書き込んではいけません（エージェント行動ガイドライン、項目5）。
• ファイル内に inspector::Nodes があるか確認してください。これがある場合、ユーザーは少なくとも一度シーンを Creator Hub で開いており、ファイルは編集モードになっています。追加する新しいエンティティはすべて inspector::Nodes に登録する必要があります。登録しないと、ゲーム内ではレンダリングされますが、Creator Hub のエンティティツリーでは見えず、選択もできません。正確な手順については、{baseDir}/../composites/composite-reference.md の「既存のコンポジットの編集（編集モード）」セクションを参照してください。

個別スキル

このスキルは入口です。詳細な実装ガイダンスは、個別にインストールできるトピック別スキルにあります。特定のスキルをインストールするか、すべてをインストールするには --skill '*' を使用してください。

シーンのセットアップと設定

スキル：create-scene — 足場の作成、scene.json スキーマ、複数区画のレイアウト、コンポジットと TypeScript エンティティのルール。

3D モデル

スキル：add-3d-models — GltfContainer を使った .glb／.gltf の読み込み、配置、コライダー、無料アセットカタログ（8,800 以上の OpenDCL モデルと Creator Hub のアセットパック）の検索。また、Blender の操作（ヘッドレス CLI または Blender MCP）によるカスタムモデルの作成と編集。

アニメーションとトゥイーン

スキル：animations-tweens — Animator を使った GLTF アニメーションクリップ、プログラムによる Tween と TweenSequence、イージング関数。

マテリアルとレンダリング

スキル：advanced-rendering — PBR マテリアル、TextShape、Billboard、VisibilityComponent、テクスチャモード。

ライティングと環境

スキル：lighting-environment — ポイントライト／スポットライト、シャドウ、SkyboxTime（昼夜サイクル）、エミッシブマテリアル。

パーティクルシステム

スキル：particle-system — 炎、煙、火花、雪、雨、魔法、花火に使用する ParticleSystem コンポーネント。エミッターの形状（Point／Sphere／Cone／Box）、連続レートとバースト放出、重力、スプライトシートアニメーション、ブレンドモード。

クリックと近接インタラクション

スキル：add-interactivity — pointerEventsSystem、トリガーエリア、レイキャスティング。ポーリングベースの入力については、advanced-input を参照してください。

高度な入力と移動制御

スキル：advanced-input — inputSystem のポーリング、WASD で操作するエンティティ、InputModifier、PointerLock、PrimaryPointerInfo、TouchScreenControls（モバイルの画面上のジョイスティック／照準／ボタン）。

プレイヤーとアバター

スキル：player-avatar — プレイヤーの位置／プロフィール、エモート、ウェアラブル、AvatarAttach、AvatarNametag、AvatarModifierArea。

アバターアニメーション（カスタムエモート）

スキル：avatar-animations — 公式 Decentraland リグを使った Blender でのカスタムアバターアニメーションの作成：リグコントロール、ポーズのルール、*_emote.glb へのエクスポート、GLB の検証、上半身（マスク済み）クリップ。

NPC

スキル：npcs — AvatarShape の NPC と、GLB ベースの NPC に会話とステートマシンを追加する NPC Toolkit ライブラリ。

プレイヤーの物理演算

スキル：player-physics — インパルス力、ノックバック、反発フィールド。

カメラ

スキル：camera-control — カメラの状態、CameraModeArea、映画のようなショット向けの VirtualCamera。

フォント

スキル：fonts — TextShape とすべての UI テキストで使える、組み込みフォント（font）とシーンに同梱するカスタム .ttf フォント（fontSrc）。Explorer の対応状況一覧、モバイルで非対応であること、制限、ライセンス、デスクトップクライアントでカスタムフォントがアセットバンドルからのみ表示される理由。

スクリーンスペース UI

スキル：build-ui — 2D スクリーンスペース UI オーバーレイ用の React ECS コンポーネント：レイアウト、テキスト、画像、ボタン、入力、スライダー。デフォルトでは、Creator Hub の 2D UI エディター（UI Designer）で読み取りと編集ができる形式で UI を作成します。これには、src/ui/ のコンポーネントごとのファイルレイアウト、state／props のバインディングインターフェイス、useInteraction のスタイルレイヤー、@ui-action ハンドラー、アニメーションをエディターの編集対象外に保つドライバーパターンが含まれます。エディターで表現できないデータ駆動型 UI に限り、自由形式のコード記述による React-ECS に切り替えます。また、既存のコード記述による UI をエディター向けに調整する方法も扱います。

プレイヤーのフィードバックとプレイテスト

スキル：scene-feedback — クリエイターがプレイテストの重点を選び、調整した質問とタイミングを確認してから、ゲームプレイに関する質問やプレイヤーが開くフォームを組み込めるよう支援します。また、World シーンの Storage にある既存の Scene Feedback CSV 回答を取得して分析する場合にも使用します。

オーディオとビデオ

スキル：audio-video — AudioSource、AudioStream、VideoPlayer、メディアの権限。

オーディオ分析（リアクティブビジュアライザー）

スキル：audio-analysis — AudioAnalysis コンポーネントを使用して、あらゆる AudioSource／AudioStream／VideoPlayer からリアルタイムの振幅と8バンドの周波数データを取得します。音楽に合わせてスケール、色、ライト、パーティクルを動かします。Unity-explorer のみで利用できます。

ブロックチェーンとNFT

スキル：nft-blockchain — NftShape、ウォレットチェック、トークンゲーティング、署名付きリクエスト、スマートコントラクト。

マルチプレイヤー（CRDT、サーバー不要）

スキル：multiplayer-sync — ピアツーピア同期のための syncEntity、MessageBus、親子同期。

マルチプレイヤーサーバー

スキル：authoritative-server — ヘッドレスサーバー、isServer()、registerMessages()、Storage、EnvVar。@dcl/sdk@auth-server が必要です。

スクリプトコンポーネント（Creator Hub）

スキル：script-components — Creator Hub の Script コンポーネント用 .ts スクリプトファイルの作成、コンストラクターのパラメーター、@action JSDoc タグ（デコレーター構文は使用しません）。

Creator Hub MCP（シーンのライブ編集）

スキル：creator-hub-mcp — Creator Hub の MCP サーバーを通じて、Creator Hub で開いているシーンを編集します。ツールカタログ（scene_state、create_entity、set_component、place_smart_item、attach_script、set_scene_settings、launch_preview、…）、読み取り後に書き込むワークフロー、カタログアイテムやカスタムモデルの配置方法、外部エージェント（Claude Code、Cursor、Codex）との接続方法を扱います。シーンが Creator Hub で開いている場合にエンティティを変更するための推奨方法です。main.composite を編集する代わりに使用します。

Explorer でのテスト（MCP）

スキル：unity-explorer-mcp — MCP 自動化サーバーを通じて、実行中の Decentraland Explorer を操作します。起動、カメラとプレイヤーの移動、スクリーンショット、ログ、パフォーマンス統計を扱います。Creator Hub 内では、同じツールを Creator Hub MCP の launch_preview／explorer_* 経由で利用できます。

非同期処理、HTTP、WebSocket、タイマー

スキル：scene-runtime — executeTask、fetch、signedFetch、WebSocket、タイマー、realm／シーン情報、制限付きアクション。

シーンの最適化

スキル：optimize-scene — シーンの制限、オブジェクトプーリング、LOD、テクスチャの最適化、システムのスロットリング。

ゲームデザイン

スキル：game-design — DCL の設計思想、状態管理、UX ガイドライン、ゲームループのアーキタイプ、MVP の計画。

スキル：unity-explorer-mcp — Decentraland Explorer を起動し、MCP 経由で操作して、シーンをワールド内で見たり、歩いたり、クリックしたり、スクリーンショットを撮ったり、デバッグしたりします。explorer MCP サーバーがセッション開始時に ConnectionRefused を報告する場合や、まだセットアップされていない場合にも、このスキルが役立ちます。いずれの場合も、Explorer がまだ起動していないことを意味します。

デプロイ

• スキル：deploy-scene — Genesis City へのデプロイ、dcl deploy、トラブルシューティング。
• スキル：deploy-worlds — Personal Worlds、worldConfiguration、ENS／DCL NAME の要件。

SDK の問題を報告する

スキル：report-sdk-issue — 回避策に取り組む前に、SDK、エンジン、Explorer のバグや制限を Decentraland チームに報告します。シーンごとに一度だけ同意を求め、ローカルの無視リストで二重送信を防ぎ、オフライン時は報告をキューに追加します。

シーンの振り返り

スキル：scene-retro — ユーザーがシーンやゲームの振り返り、レトロスペクティブ、ポストモーテムを依頼した場合（「このゲームを基にレトロレポートを作成して」など）、セッション履歴を確認し、実際のミス、最初の試行の失敗、オーナーによる修正を、これらのスキルを改善するための根拠付きの提案にまとめます。読み取り専用です。レポートを保存しますが、それ以外は何も変更しません。

SDK6 → SDK7 の移行

スキル：migrate-sdk6-to-sdk7 — レガシーな decentraland-ecs シーンを SDK7 に移行します。ECS の概念的な変更（ID としてのエンティティ、データのみのコンポーネント、可変／不変アクセス）、API の完全な対応表（new Entity() → engine.addEntity()、GLTFShape → GltfContainer、OnPointerDown → pointerEventsSystem、ISystem クラス → フリー関数、Input.instance → inputSystem など）、注釈付きの移行前／移行後の例を扱います。

---

用語 — 非推奨のツール名

古い名称は、チュートリアルやフォーラムへの投稿、モデルが生成した回答などで今も使われています。ユーザーにこれらの名称を提示しないでください。また、ユーザーがこれらの名称を使った場合は、現在の名称に言い換えてください。

非推奨の名称	以前の用途	代わりに使う名称
Web Editor	ブラウザー上で動作するシーンエディター	Creator Hub
Decentraland Editor	Visual Studio Code の拡張機能	Creator Hub
SDK6	旧 SDK。現在の Decentraland では、そのコードは動作しません	SDK7（古いシーンの移行については、migrate-sdk6-to-sdk7 スキルを参照してください）
dclcontext folder	シーンプロジェクト内にダウンロードされた AI コンテキストファイル	SDK Skills（これらのスキル）

現在の名称：Creator Hub、Scene Editor、SDK7、SDK Skills。ドキュメントの用語集のコミット 4b6733c に照らして確認済みです。

共有リファレンス

これらのリファレンスファイルは、複数のスキルで使用されます。コンポーネント API、検証ルール、アセットカタログの詳細が必要な場合は読み込んでください。

コンポーネントのリファレンス

リファレンス：{baseDir}/references/components-reference.md SDK7 コンポーネントでよく使用される主なフィールド、型、デフォルト値をすぐに確認できます。コンポーネントのフィールド一覧全体を確認するには、専用のスキルまたは SDK の型定義を参照してください。

エンティティ検証ルール

リファレンス：{baseDir}/../create-scene/references/entity-validation-rules.md エンティティのコンポーネントの組み合わせを検証するためのルールです。相互に必要なコンポーネント、併用できないコンポーネント、よくある設定ミスについて説明しています。コンポジットエンティティと TypeScript エンティティの両方に適用してください。

無料アセットカタログ

• 3D モデル（8,800 点以上）： {baseDir}/../add-3d-models/references/model-catalog.md — 説明、寸法、アニメーション、ダウンロード URL が記載された、最適化済みの 3D モデル
• Creator Hub アセットパック（420 モデル＋7 Smart Items、最新の追加分）： {baseDir}/../add-3d-models/references/asset-pack-catalog.md — Genesis City の建物・道路・家具・自然、ハロウィン、SF 研究室キット、スクリプト付きのボタン・ドア・プラットフォーム・水。複数ファイルのダウンロードヘルパーについては model-patterns.md を参照してください
• アバターアニメーション（組み込みエモート 32 種＋ダウンロード可能なクリップ 45 種）： {baseDir}/../avatar-animations/references/animation-catalog.md — エモートを作成する前に確認してください
• オーディオ（50 種のサウンド）： {baseDir}/../audio-video/references/audio-catalog.md — 音楽、環境音、効果音、ゲームメカニクス、UI サウンド

コンポジット

リファレンス：{baseDir}/../composites/composite-reference.md 初期シーンエンティティを宣言するための .composite JSON 形式です。TypeScript でコンポジットエンティティを取得するための getEntityOrNullByName および getEntitiesByTag パターンも含まれています。

ライブラリのリファレンス

• NPC Toolkit： {baseDir}/../npcs/references/npc-library.mdc — 会話、移動、状態マシンに対応する GLB ベースの NPC
• ブロックチェーン／NFT のパターン： {baseDir}/../nft-blockchain/references/blockchain-patterns.md — NFT の表示、ウォレットの確認、MANA 操作、通貨／NFT 取引、マーケットプレイス連携（dcl-crypto-toolkit）

---

使用方法

1. ユーザーのリクエストからトピックを特定します
2. 該当するスキルを読み込みます。スキルには完全な API、コードパターン、ルールが含まれています
3. 複数のトピックにまたがる広範なリクエストの場合は、関連するスキルをそれぞれ読み込みます
4. アセットを探す場合は、該当するカタログを読み込み、取得する前に具体的なアセットを提案します