decentraland-sdk-skills

Decentraland SDK7 シーン開発

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

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

重要な操作を行う前に、以下の3つのカテゴリのいずれかに該当するかを確認し、必ず先にユーザーに確認してください。

質問のしかた： 基盤となるコマンドではなく、_シーンにどのような変更が加わるか_を説明する、平易で技術的すぎない言葉で質問してください。

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

1. パーセル数またはレイアウトの変更

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

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

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 ブランチに切り替える必要があります。こちらをご希望ですか？それとも、用途にはよりシンプルなピアツーピア同期で十分でしょうか？」

基本原則

これらはエージェントが拒否すべき操作ではなく、実行前にユーザーへ伝えるべき操作です。ユーザーが確認したら、自信を持って進めてください。目指すのは、過剰な制限ではなく透明性です。

---

重要なルール — コンポジット優先のシーン作成

すべての静的エンティティ（モデル、ライト、スポーンポイント）は、TypeScript で engine.addEntity() を使って作成するのではなく、assets/scene/main.composite で定義する必要があります。

TypeScript（src/index.ts）を使用するのは、次の目的に限ります。

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

---

個別スキル

このスキルはエントリーポイントです。詳細な実装ガイダンスは個別のトピック別スキルに記載されており、それぞれ別々にインストールできます。特定のスキルをインストールするか、すべてインストールするには --skill '*' を使用してください。

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

スキル：create-scene — スキャフォールディング、scene.json スキーマ、マルチパーセルのレイアウト、コンポジットと TypeScript におけるエンティティの使い分けルール。

3D モデル

スキル：add-3d-models — GltfContainer を使った .glb／.gltf の読み込み、配置、コライダー、無料アセットカタログ（8,800 以上のモデル）の閲覧。

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

スキル：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。

プレイヤーとアバター

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

NPC

スキル：npcs — AvatarShape を使った NPC、および会話とステートマシンを備えた GLB ベースの NPC 向け NPC Toolkit ライブラリ。

プレイヤーの物理演算

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

カメラ

スキル：camera-control — カメラの状態、CameraModeArea、シネマティックショット向けの VirtualCamera。

スクリーンスペース UI

スキル：build-ui — 2D のワールド内 UI 向け React ECS コンポーネント：レイアウト、テキスト、画像、ボタン、入力欄。

音声と動画

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

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

スキル：audio-analysis — あらゆる AudioSource／AudioStream／VideoPlayer の振幅と8バンド周波数データをリアルタイムで取得する AudioAnalysis コンポーネント。音楽に合わせてスケール、色、ライト、パーティクルを動かします。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 コンポーネント向け .tsx スクリプトファイルの作成、コンストラクターのパラメーター、@action() デコレーター。

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

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

シーンの最適化

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

ゲームデザイン

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

デプロイ

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

SDK6 から SDK7 への移行

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

---

共通リファレンス

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

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

リファレンス：{baseDir}/sdk-scenes/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 モデル
• オーディオ（50 種類のサウンド）： {baseDir}/audio-video/references/audio-catalog.md — 音楽、環境音、効果音、ゲームメカニクス、UI サウンド

コンポジット

参照：{baseDir}/composites/composite-reference.md 初期シーンのエンティティを宣言する .composite JSON 形式について説明します。TypeScript でコンポジットエンティティを取得する getEntityOrNullByName と getEntitiesByTag のパターンも含みます。

ライブラリリファレンス

• NPC ツールキット： {baseDir}/npcs/references/npc-library.mdc — ダイアログ、移動、ステートマシンを備えた GLB ベースの NPC
• Crypto/MANA： {baseDir}/nft-blockchain/references/crypto-library.mdc — MANA の操作、通貨／NFT の取引、マーケットプレイスとの連携

---

使用方法

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