msw-ui-kit

msw-ui-kit

公式の MSWPackages アセットを再利用して、視覚的に統一感のある UI を構築します。公開済みのワールドからテーマ別の RUID パレットを選び、事前に構築されたインタラクションウィジェットライブラリを利用できます。1 つのリソースパックにまとめて収録されたパーツは、すでに互いに調和するようアートディレクションされています。検索で RUID を場当たり的に組み合わせるより、1 つのテーマから選ぶほうが効果的です。

役割分担：

スキル	担当
msw-ui-kit（このスキル）	使用するアセット — テーマ別のパーツ RUID、画面サンプルの参照、事前構築済みウィジェットの統合
msw-ui-system	.ui 自体 — すべての .ui の作成・変更は、その UIBuilder を通じて行います。レイアウト、アンカー、コンポーネントを担当します
msw-packages	機能システム（インベントリのロジック、ショップのロジック、ランキングデータなど）— このスキルが扱うのは 見た目 と インタラクションウィジェット のみです

---

0. 振り分け

トリガー	参照先
「洗練された／きれいな／ゲーム品質の UI」、「テーマ付き画面」、テーマが選択済み	references/themes/<theme>.md — まず §1 の表から選びます
特定のパーツを探す場合（「このテーマの閉じるボタン／矢印／スロットのバリエーション／ゲージ」）	テーマのドキュメントにあるパーツ一覧。対象が少ない場合は、data/themes/<theme>.ruids.json を名前のキーワードで grep します
「チェックボックス／ラジオボタン／スイッチ／トグルグループ／ドロップダウン／ページネーション／プログレスバー／スクロールピッカー／タイムピッカー／テンキー／スピナー」	references/widgets.md
画面全体の構成を参照する場合（「実際のゲームのようなインベントリ／ショップ／ランキング画面を作成する」）	テーマのドキュメントの「サンプル画面」§ → data/samples/<theme>/<Screen>.txt の同梱ツリーを読みます
同上。ただし機能が公式パッケージ由来の場合（インベントリ／ショップ／メール／ランキング／クエスト／ダイアログなど）	references/package-screens.md → data/packages/<package>/<Screen>.txt
画面の裏側にある機能ロジック（インベントリへの追加・削除、購入フローなど）	msw-packages スキルに振り分けます

1. テーマの選択

ワールドごとに テーマを 1 つ選び（最低でも画面群ごとに 1 つ）、そのテーマ内に統一します。テーマ内のすべてのパーツは、互いに調和するようアートディレクションされています。

テーマ	元のワールド	特徴／最適な用途	収録数
supersimple	Getting Over It Maker	すっきりとしたミニマルなユーティリティ UI。軽量ゲームやツール風の画面	コアセット 9 種、サンプル画面 19 件
simplefantasy	MapleSlash	ファンタジーアクション RPG。装備／スキル／ガチャ／スターフォース画面を含む最大規模のキット	コアセット 11 種、サンプル画面 42 件
casualrpg	MapleSoulHero	カジュアル RPG のフルセット（インベントリ、クエスト、コレクション、ステージマップ）	コアセット 11 種、サンプル画面 20 件
casualsurvival	Durango The Lost Island	サバイバル／クラフト（研究、クラフト、ミニマップ、ステータス）	コアセット 10 種、サンプル画面 15 件
cutecasual	ChuChuBurger	かわいらしい丸みのある経営／タイクーン風スタイル。サンプル数は最多	コアセット 10 種、サンプル画面 28 件
cardgame	Maple Duel	カードバトル（カード、ミニオン、ランクマッチ、デッキ）	コアセット 8 種、サンプル画面 12 件
minimalcombat	Maple Auto Battler	コアのみの小規模なセット（アイコン、スロット、色合い）— アクセント用	コアセット 5 種、サンプルなし

ユーザーに希望がない場合、ユーティリティ／軽量なワールドには supersimple、RPG 風のワールドには simplefantasy を選びます。選択したテーマと理由を 1 行で伝えます。

2. ワークフロー

(1) Pick theme          §1 table (ask only if genuinely ambiguous)
(2) Load palette        references/themes/<theme>.md
(3) Structure first     building a standard screen (inventory/shop/ranking/HUD/dialog…)?
                        read data/samples/<theme>/<Screen>.txt BEFORE laying anything out
                        (large files say so in their header — read top-level sections, not all)
                        feature comes from an official package? use data/packages/ instead
                        (references/package-screens.md indexes them)
(4) Map screen parts    panel → surface part, actions → button parts, lists → slot/unit parts,
                        gauges → slider parts, glyphs → tint/icon parts
(5) Build via builder   msw-ui-system UIBuilder, passing image_ruid per part
(6) Widgets if needed   references/widgets.md (binding groups + assets/widgets/trees/ blueprint)

3. ルール

ALWAYS

1. 画面ごとにテーマを1つにし、作成時に固定します。 このスキルでは、.ui の作成時にテーマを選択し、実行時には変更しないことを前提としています。これにより、ALWAYS #4 で「このテキストはテーマアートの上に配置されているか」を作成時に確認できる事実として扱えます。1つの画面で2つのテーマのパーツを混在させないでください。必要なパーツがない場合は、まずテーマの data/themes/<theme>.ruids.json のロングテールを grep し、次に同じテーマの別サイズのパーツを再利用し、それでも見つからない場合に限り msw-search を使ってください。実行時にテーマが本当に切り替わる場合、この前提は崩れます。作成したプレーンなパネルが、後からテーマアートの下に入る可能性があるためです。その場合は、切り替え可能なサーフェスとその上のテキストを同じテーマセットにまとめるか、切り替え対象からそのクロームを完全に外し、色を調整してください。
2. ネイティブサイズを尊重してください。 非スライスのパーツはネイティブのアスペクト比を保ちます（均等に拡大縮小します）。(Sliced) パーツはサイズ変更できますが、9スライスで維持されるのは境界線だけです。アート内に描かれた帯、区切り線、内枠は中央部分と一緒に引き伸ばされ、コンテンツの上に重なりますが、目視や lint では検出できません。汎用のウィンドウ／ポップアップ背景には、テーマのドキュメントにあるパーツ一覧から、ネイティブの W:H が目的の矩形に最も近いものを選んでください。サンプルツリーから背景を再利用する前に、データ JSON でその RUID を grep してください。"kind": "S" はサンプル画面にしか存在しないことを意味します。これはそのレイアウト用のフィクスチャであり、汎用サーフェスではありません。(Tiled) パーツは繰り返しで伸長します。ただし、例外が1つあります。(Tiled) と記されたゲージ／バーの背景では、バーの幅がネイティブサイズと異なる場合に sprite_type: 1（Sliced）を使ってください（タイル表示では末尾の一部分が切り取られ、位置がずれて見えます）。BG_Pattern 系のような大きな装飾パターンの塗りつぶしには、Tiled を使ってください。サイズ変更するサーフェスのデフォルト：サーフェス型のパーツ（ウィンドウ背景、パネル、リスト／行の背景、プレート）をネイティブ以外のサイズで使う場合は、マーカーにかかわらず sprite_type: 1 を指定してください。9スライスの境界線があればきれいに描画され、なければ Simple と同じ表示になるため、Simple より悪くなることはありません。アイコン／イラストはサーフェスではないため、均等に拡大縮小してください。(Filled) は記録であり、指示ではありません：これは、ソースでそのアートをネイティブサイズの FillAmount で処理していたことを示し、通常は SliderComponent の中で使われていました。独自のリニアゲージでは、msw-ui-system のルールに従い、塗りつぶすのではなくフィルスプライトの幅を変更してください。Filled は UV をクリップし、9スライスの境界線を歪めます。まず sprite_type: 1 を使ってください。ゲージのフィルは細長いグラデーションで、スライス境界線がないことも多いため、引き伸ばされたりぼやけたりする場合は、パターンをきれいに繰り返す sprite_type: 2（Tiled）に切り替えてください。Filled は放射状のスイープ（クールダウンリング）に限って使ってください。(Filled) パーツのネイティブのアスペクト比は維持しないでください。こうしたアートは 48:1 のような極端な比率になるため、均等に拡大縮小すると、使えるバーにならないことがあります。
3. テーマ付きパーツには必ず明示的な color を指定してください。 image_ruid だけを渡すと、ビルダーの濃い半透明のデフォルトスキンカラーがスプライトに適用され、アートがほとんど見えない状態になります。セルや、実行時に画像を差し替えるアイコンも含め、パーツを作成時の見た目どおりに描画するには "#FFFFFF" を渡してください（button／slider／textInput では bg_color を指定します。ただし、テーマのドキュメントで color: 値が記載されているパーツには、その値を使ってください）。Tint_* パーツはモノクロのグリフです。色付きアイコンを探すのではなく、ビルダーの color オプションでテーマに合ったアクセントカラーを適用してください。これはサーフェスにも当てはまります。一部のパネル／行／ユニット背景は、Tint_* エントリと同じ RUID を持つニュートラルな白いマスクです。そのままでは一面の白（またはほとんど見えない）塗りつぶしになり、テキストが埋もれてしまいます。color: 値が記載されているパーツには、必ずその色（またはテーマに合った意図的な代替色）をビルダーに渡してください。RUID をそのまま描画してはいけません。マスクの RUID には、データ JSON で "tint": true のフラグが付いています。
4. テーマアート上のフォントカラーを独自に決めないでください。 スプライトの明るさは目視できないため、明るい背景に明るい文字、暗い背景に暗い文字といった失敗を静的には検出できません。テーマのドキュメントにある、パーツと text: の組み合わせを使ってください。そこには、ソースのワールドで実際にそのアートに使われたフォントカラーが使用頻度順に、回数とともに記載されています。+o#RRGGBB（アウトライン）または +s#RRGGBB（フラットなハロー）が付いた組み合わせは、色とセットで扱ってください。これらのパックの明るいフォントカラーの多くは、その縁取りがあって初めて読みやすくなります。色だけを使うと、同じ問題が再発します。テキストノードの outline／outline_color／outline_width にアウトラインを渡してください。ハローは patchComponent で Underlay と UnderlayColor を設定し、オフセットを 0 にしてください（ドロップシャドウではなく、均一な縁取りにします）。該当する組み合わせがない場合は、テーマの「Text colors」セクションから（最も近い用途に合うものを）選んでください。黒／白をそのまま使うのは、自分で用意した単色パネルの上だけにしてください。[split surface] と記されたパーツ（データ JSON では "split_text": true）には、淡い本文の上にあるタイトル帯など、明るい領域と暗い領域の両方が含まれます。そのため、記載された色を相互に置き換えて使うことはできません。文字を配置する領域に合わせて選び、判断に迷ったら、淡い領域でも読みやすい暗い色を優先してください。
5. .ui の変更はすべて msw-ui-system の UIBuilder 経由で行ってください — このスキルが提供するのは RUID／サイズ／構造のみです。アンカー、ネスト、UIGroup ルートなどの設計ルールも適用されます。
6. サンプル画面とパッケージ画面は構造の参考資料であり、コピーするファイルではありません — パーツの構成を調べたうえで、ビルダーを使って組み直してください。パッケージ画面にはパッケージ独自のアートが含まれているため、その構成を活用し、自分のテーマの RUID を渡してください。その機能自体がパッケージ由来の場合は、スクリプトがそのツリーを参照して動作するため、パッケージ画面を優先してください。

絶対にしないこと

1. ui-resource-* パッケージをインストールしたり、コピーしたりしないでください。RUID は MSW リソースストレージからそのまま解決されます。ワークスペースにコピーするのはウィジェットのみで、そのソースは**このスキルの assets/widgets/**です（references/widgets.md を参照）。ネットワークから何も取得しないでください。
2. ウィジェットのプレハブ内部（スクリプト名、子の名前）を手作業で編集しないでください。バインドは名前で行われます。

4. サブドキュメント

• references/themes/ — テーマごとのパーツパレット：supersimple.md、simplefantasy.md、casualrpg.md、casualsurvival.md、cutecasual.md、cardgame.md、minimalcombat.md
• references/widgets.md — 事前構築済みのインタラクションウィジェット：統合、ウィジェットごとの API、バインドグループ、イベント、注意点
• references/package-screens.md — 公式機能パッケージの画面（インベントリ、ショップ、メール、ランキング、クエストなど）のインデックス。画面ツリーは data/packages/<package>/<Screen>.txt に記録されています
• data/themes/<theme>.ruids.json — テーマごとの完全な RUID レジストリ（機械検索可能な詳細情報。1 行につき 1 つの JSON オブジェクト：名前、カテゴリ、kind（アートが登場するモデルを示します — C はコアパレットのみ、S はサンプル画面のみ、CS は両方）、サイズ、type — これはソースワールドでそのアートがどのように描画されたかの記録であり、使用方法の推奨ではありません。実際に渡す値については ALWAYS #2 を参照してください。さらに、伸縮して表示するサーフェスに分類されたパーツには "surface": true（ALWAYS #2 のデフォルトの Sliced 対象）、明示的な color が必要なニュートラルマスクには "tint": true（ALWAYS #3 の対象）が付きます。また、"text" はソースワールドがそのアートに使用したフォントカラーを件数と +o／+s のリングとともに示し、明るい領域と暗い領域の両方にまたがる場合は "split_text": true が付きます（ALWAYS #4 の対象）
• data/samples/<theme>/<Screen>.txt — ソースワールドの本番画面のエンティティツリー全体のダイジェスト（構造レシピ）
• assets/widgets/ — 同梱のウィジェットソース：UIComponent/**/*.mlua と Util/Util.mlua（ワークスペースにコピー）および trees/**.txt のプレハブ構造ダイジェスト（テーマパーツを使ってビジュアルを再構築）

対象外

• .ui の構築方法、アンカー、コンポーネント、ランタイムのパターン — msw-ui-system
• 機能／システムパッケージ（インベントリ、ショップ、メール、ランキングのロジックなど） — msw-packages
• テーマ外の自由形式のスプライト検索 — msw-search。新しいスプライトの描画 — msw-painter