msw-packages

MSW Packages — 公式プリビルトカタログ

MSW-Git/MSWPackages は、プリビルト機能パッケージを集めた MSW 公式のファーストパーティリポジトリです。一般的なゲーム機能を一から実装する前に、まずこのカタログを確認してください。該当するパッケージがある場合は、ゼロから実装するのではなく、統合を提案してください。

このスキルは簡易インデックスです。パッケージごとの詳細（README、ソース、統合手順）はここに複製せず、必要に応じて GitHub から取得するため、カタログは自動的に最新の状態に保たれます。

---

判断フロー

User asks for feature X
        │
        ▼
Match X against Feature → Package table below
        │
   ┌────┴─────┐
   │ Match    │ No match
   ▼          ▼
Scope-First check      Proceed with normal MSW
(see section below):   authoring (msw-scripting,
system vs UI-only?     msw-search, etc.)
        │
   ┌────┴───────────┐
   │ system         │ UI-only
   ▼                ▼
Fetch package    Route to msw-ui-system
README           (+ references/templates/, skip the rest of this skill)
        │
        ▼
Summarize for user
"Found <package>. README says: <summary>.
 Integrate this, or build from scratch?"
        │
   ┌────┴─────┐
   │          │
   ▼          ▼
Integrate    Build from scratch
        │
        ▼
Run Integration Workflow (below)

基本方針：統合する前にユーザーへ確認してください。確認なしに自動インストールしてはいけません。パッケージが、ユーザーのプロジェクト内にある既存の UUID、スプライトの RUID、命名規則と衝突する可能性があります。

---

機能 → パッケージの対応表

ユーザーのリクエストに以下の機能（韓国語または英語）が含まれている場合、該当するパッケージを調べ、まず README を取得してください。

機能分野	パッケージ	GitHub パス
トースト／通知／バナー	maplestory-toast-package	リンク
ランキング／リーダーボード／スコアボード（基本）	ranking-basic-package	リンク
ランキング／リーダーボード（高度 — 複数ボード、シーズン）	ranking-advanced-package	リンク
インベントリ／アイテムバッグ／装備	inventory-package	リンク
ショップ／ストア／購入	shop-package	リンク
ワールドショップ／プレミアムショップ	worldshop-package	リンク
メール／メールボックス	mail-package	リンク
クエスト／実績／ミッション	quest-achievement-package	リンク
ダイアログ／NPC 会話（タイプライター形式）	dialog-package	リンク
キーバインド／仮想ボタン	key-binding-package	リンク
ゲームイベントのブロードキャスト／パブサブ	game-event-package	リンク
プレイヤーデータ／セーブ／プロフィール	player-data-package	リンク
コレクション／ギャラリー／図鑑	collections-package	リンク
スラッシュコマンド／チャットコマンド	command-package	リンク
仮想化スクロールリスト／大規模リスト	recyclescrollview-package	リンク
ドロップテーブル／戦利品の確率	droptable-resolver-package	リンク
グローバル設定／共有設定	global-config-package	リンク
GM／システム告知	gm-message-package	リンク
ゲームリソース（通貨、エネルギー、補充可能なリソース）	resource-package	リンク
UI コンポーネントとプレハブモデル	ui-component-package	リンク

複数のパッケージが該当する可能性がある場合（例：「ランキング」→基本版または高度版）は、両方の README を取得し、比較をもとにユーザーが選べるようにしてください。

---

スコープ優先のルーティング（UI とシステム）

リクエストがカタログのキーワードに一致するものの、ユーザーがシステム全体（データ＋ロジック＋UI）を求めているのか、UI 画面だけを求めているのかが不明な場合は、パッケージファイルを取得する前に、短い質問を1つだけしてください。以下の表から該当する行を使用してください。

リクエストのキーワード	質問
ランキング／リーダーボード	「スコアの保存や順位の計算も必要ですか？それともリーダーボード画面だけですか？」
インベントリ／バッグ	「アイテムの追加・削除ロジックも必要ですか？それともスロット画面だけですか？」
ショップ／ストア	「通貨の差し引きや購入処理も必要ですか？それともショップ画面だけですか？」
メール／メールボックス	「送受信のロジックも必要ですか？それともメールボックス画面だけですか？」
クエスト／実績	「進行状況の追跡や報酬も必要ですか？それともクエスト一覧画面だけですか？」
トースト／通知	「キュー管理やタイミングのシステムも必要ですか？それともメッセージのポップアップだけですか？」
ダイアログ／NPC との会話	「分岐する会話や状態管理も必要ですか？それともダイアログウィンドウだけですか？」
コレクション／図鑑	「コレクションの状態や進行状況の追跡も必要ですか？それとも図鑑画面だけですか？」
プレイヤーデータ／セーブ	「永続化やロード／セーブのフローも必要ですか？それともプロフィール画面だけですか？」
その他／不明	「機能として動作するものが必要ですか？それとも UI 画面だけですか？」

ルーティングルール

ユーザーの回答に応じて、行き先を決めます。

ユーザーの回答…	ルーティング先
「機能」「システム」「ロジック」「保存」「計算」「処理」「実行」	ここ（msw-packages）にとどまる — 以下の Fetch Protocol に進みます
「画面」「UI」「見た目」「ビジュアル」「レイアウトだけ」「表示だけ」	msw-ui-system スキル（＋ references/templates/）— スタイルテンプレートを選び、UI ビルダーを使って作成します
低レベルの質問（アンカー、コンポーネントのプロパティ、列挙型）	msw-ui-system スキル — references/component-api.md（§Enums を含む）／ui-fundamentals.md を参照して直接回答します。取得は不要です

質問を省略する場合

ユーザーのリクエストがすでに明確な場合は、Scope-First の質問を省略し、直接ルーティングします。

• 「一から」「UI だけ」「画面だけ」→ msw-ui-system スキル（＋ references/templates/）
• 「システム全体」「バックエンド付き」「データ付き」「スコアを保存」→ msw-packages にとどまります
• UI に関する純粋な低レベルの質問（例：「アンカーの設定方法は？」）→ msw-ui-system スキル

キーワードがカタログのパッケージに一致し、スコープが本当に曖昧な場合にのみ質問してください。

---

Fetch Protocol

候補となるパッケージが特定された場合：

1. まず README（常に実施）

https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<package-name>/README.md

これを取得するには WebFetch を使用します。先に進む前に、公開 API とユースケースをユーザーに要約して伝えてください。

2. ファイルツリー（統合の可能性が高い場合）

GitHub のツリー API を使用し、パッケージパスを grep します。

https://api.github.com/repos/MSW-Git/MSWPackages/git/trees/main?recursive=1

応答は大きく、途中で切り詰められる場合があります。応答を grep して <package-name>/ を探し、ファイル一覧を抽出してください。途中で切り詰められている場合は、ディレクトリごとのツリー呼び出しに切り替えてください。

https://api.github.com/repos/MSW-Git/MSWPackages/contents/<package-name>/MyDesk

標準的なパッケージの構成：

• <package-name>/README.md
• <package-name>/<PackageName>.modpackage — インストーラーマニフェスト（内容を解釈しないでください）
• <package-name>/MyDesk/<PackageName>/Core/ — コピーするコアスクリプト／UI
• <package-name>/MyDesk/<PackageName>/Sample/ — 使用例（依頼されない限りコピーしないでください）
• <package-name>/MyDesk/Util/ — 共通ユーティリティ（一部のパッケージ）

3. 生ファイルの取得（必要に応じてファイルごとに実施）

https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<path>

ブラウジング用 URL では、github.com/.../blob/main/... を raw.githubusercontent.com/.../main/... に置き換えてください。

---

統合ワークフロー

ユーザーが統合を承認したら：

1. ファイルをプロジェクトのレイアウトに合わせる：

   • MyDesk/<PackageName>/Core/*.mlua → RootDesk/MyDesk/<PackageName>/
   • MyDesk/<PackageName>/Core/*.ui → ui/
   • MyDesk/<PackageName>/Core/*.model → RootDesk/MyDesk/Models/<Category>/
   • MyDesk/Util/* → RootDesk/MyDesk/Util/（すでに存在する場合は再利用）

2. UUID の衝突を確認する：受信する .ui／.model ファイル内のすべてのエンティティ id と EntryKey が、ユーザーのプロジェクトにすでに存在していないことを確認します。書き込む前にワークスペースを grep して衝突がないか調べます。衝突する UUID は、新しい 16 進数 UUID を生成して置き換えます。

3. スプライト RUID の依存関係を確認する：パッケージファイルをスキャンして、ハードコードされた RUID を探します。これらは MSW のコミュニティリソースを参照しています。通常は問題ありませんが、疑わしいものがある場合や代替が必要な場合は msw-search で確認してください。

4. パッケージ間の依存関係を解決する：パッケージによっては、ほかのパッケージに依存します（例：ランキングはプレイヤーデータを基盤としている場合があります）。パッケージの README とソースヘッダーを読み、推移的な依存パッケージを先にインストールしてから、このパッケージをインストールします。

5. 標準の MSW ワークフローで適用します：stop → refresh_workspace → play。ビルドログとランタイムログで確認します。

6. ユーザーのコードに接続する：ほとんどのパッケージは _<PackageName> という Logic シングルトンを公開します。ユーザーの既存スクリプトからその API を呼び出します（例：_MaplestoryToast:Show(...)）。

---

注意点

• このワークフローでは、.modpackage ファイルは自動インストーラースクリプトではありません。Maker エディターのメタデータです。パッケージを実際に統合するには、ファイルを手動でコピーします。
• サンプル内のハードコードされたスプライト RUID：パッケージのサンプルは、装飾用スプライトの特定の RUID を参照していることがよくあります。これらは動作しますが、ユーザーが別のものに置き換えたい場合があります。要約する際は、その点に触れてください。
• UI ファイルでは、ルートエンティティに UIGroup が使われます。コピーする際は、msw-ui-system を経由してください（UIBuilder.read/load で確認し、ビルダー API で変更します。UIGroup のルート設定やアンカーモードの落とし穴などの設計ルールも、同じスキルに記載されています）。生の .ui JSON を直接編集しないでください。
• Sample/ の内容は説明用であり、本番用ではありません。ユーザーから明示的な依頼がない限り、Sample/ のファイルをコピーしないでください。サンプルスクリプトはキーボードショートカットを割り当てていることが多く、ユーザーの操作と競合する可能性があります。
• パッケージを使っても mlua の理解は不要になりません。パッケージは事前に構築された機能を提供しますが、ユーザーが拡張するには、引き続き msw-scripting の知識が必要です。
• 推測で複数のパッケージを一括インストールしないでください。統合のたびにファイルと管理対象が増えます。一度に 1 つの機能をインストールして検証してから、次に進みます。

---

ユーザーがすでに「最初から作る」を選んでいる場合

統合は完全に省略します。通常の MSW オーサリング（msw-scripting、msw-search など）を進めてください。パッケージの利用を暗黙に勧め続けないでください。

---

MSW-Git/MSWPackages にアクセスできない場合

• WebFetch がエラーまたは 404 を返す場合 → URL が変更されていないか確認します。
• サンドボックスのネットワークでは api.github.com への直接の curl がブロックされる場合があります。raw URL と HTML URL には WebFetch を優先してください。
• すべて失敗した場合は、最初から作る方法に切り替え、パッケージに現在アクセスできないことをユーザーに伝えてください。

---

相互参照

• msw-general — ワークスペース、ファイルパス、MCP ツール、座標系。
• msw-scripting — パッケージ API をゲームロジックに組み込むための .mlua 構文。
• msw-search — パッケージ同梱リソースの代替に使うスプライト／アニメーション／サウンドの RUID 検索。