msw-ui-system

msw-ui-system

MSW の .ui 用の単一エントリーポイントです。デザインガイド＋コンポーネント API＋ビルダーの呼び出し方法＋ランタイムのパターンを、ひとつのスキルにまとめています。

既存スキルとの役割分担：

スキル	担当範囲
msw-ui-system（このスキル）	.ui に関するすべて。デザイン（何を・いつ・なぜ）、コンポーネント API／列挙型（何か）、ビルダーの呼び出し方法（変更方法）、ランタイムの mlua パターン。.ui の変更には、必ずこのスキルのビルダーを使用してください
references/templates/	事前構築済みのスタイルバンドル（.ui＋ruid-map＋ボタンハンドラーパッケージ）

---

0. ルーティング

リクエストのキーワードに基づいて、サブリファレンスに進んでください。

トリガー	リファレンスドキュメント
「アンカー／ピボット／座標／位置がおかしい理由」、「RectTransform」、「ストレッチ」	references/ui-fundamentals.md §1～§8
「モバイル」、「セーフエリア」、「1920」、「MobileOnly」、「ActivePlatform」、「タッチサイズ」、「PC の予約領域」、「デバイス別フォントサイズ」	references/ui-fundamentals.md §9
「UIGroup」、「ポップアップの上」、「z-order」、「displayOrder」、「CanvasGroup」、「不透明度の伝播」、「Enable と Visible の違い」	references/ui-hierarchy.md。ランタイムの兄弟順序の変更については、references/runtime-patterns.md §7 も参照してください
「どのコンポーネントか」、「Sprite と Text と Button の違い」、「9 スライス」、「スクロールリスト」、「GridView と ScrollLayoutGroup の違い」	references/component-api.md §「コンポーネント選択ガイド」
「スプライトのピボット」、「9 スライスの境界線」、「スライスの境界」、「スライス済みアセットのメタデータ設定」、「リソースの保存プロパティ」	msw-mcp の asset_update_resource_storage_info を使って、アセット側のメタデータを直接設定してください。.ui 側については、references/component-api.md §「SpriteGUIRenderer — ImageType の選択」を参照してください
「HUD の作成」、「ポップアップの配置」、「トースト」、「メニュー」、「インベントリグリッド」、「スクロールリスト」、「ランキング」、「リーダーボード」、「クエストリスト」、「フレンドリスト」、「メールボックス」	references/layout-recipes.md
.ui ビルダーで構築した後に .mlua を接続する、「プロパティのデフォルト UUID」、「ドラッグせずにバインド」	../msw-general/references/builder-protocol-ui.md §3.6 バインディングの注入（統合エントリーポイント。builder-protocol.md のコアと一緒に読み込んでください）
ランタイムでの UI コンポーネントフィールドの読み書き、コンポーネントのプロパティ名／型（ButtonComponent.Colors、TextGUIRendererComponent.Overflow、SpriteGUIRendererComponent.FillAmount など）	UI コンポーネントフィールドに .mlua からアクセスする前に、毎回 references/component-api.md を参照してください
列挙型の値（AlignmentType、TextOverflowMode、ImageType、UIBasicParticleType など）	references/component-api.md §列挙型
ランタイムの mlua パターン（ポップアップの開閉、トーストのフェード、HP バー、GridView、ドラッグ、タブ、クールダウン）、ランタイム UI の注意事項（クライアント専用、サーバー側では nil など）	references/runtime-patterns.md
.ui ビルダーの呼び出し方法（UIBuilder API、アンカープリセット、書き込み時の自動リンティング、コンポーネントの追加／パッチ適用／削除）	../msw-general/references/builder-protocol-ui.md §3 UIBuilder（統合エントリーポイント。builder-protocol.md のコアと一緒に読み込んでください。.map の MapBuilder と .model の ModelBuilder は、兄弟ファイルの各ビルダー用ファイルにあります）
「サウンド」、「sfx」、「クリック音」、「ホバー音」、「ボタンの音声」、「PlaySound」	references/ui-sound.md

---

1. 基本的なワークフロー

(1) Clarify intent       Layout sketch (ASCII or verbal) + which group to attach to
(2) Check design guide   Match at least one of ui-fundamentals / ui-hierarchy / component-api §Component Selection Guide
(3) Builder Preflight    Read ../msw-general/references/builder-protocol.md (core) + builder-protocol-ui.md §3 (unified call-protocol entry point)
(4) Match recipe          Select the closest template from layout-recipes.md
(5) Invoke builder        Create/patch via scripts/msw_ui_builder.cjs (protocol: builder-protocol-ui.md §3)
(6) Inject bindings       Auto-inject .mlua property default UUIDs via b.write(path, { bind: {...} }) or b.injectBindings(...) (builder-protocol-ui.md §3.6 Binding Injection)
(7) Self-verify           write() auto-runs scripts/ui_lint.cjs (strict ON by default)
(8) Preview               Visual check via scripts/preview_ui_layout.cjs
(9) Sound pass            For any interactive button, offer click/hover SFX wiring (references/ui-sound.md)
(10) Maker Refresh         Apply to engine

2. グローバルルール

絶対にしないこと

1. .ui の JSON を直接編集しないでください — .ui の作成・変更は、必ず scripts/msw_ui_builder.cjs を通して行ってください。手動編集すると、UUID・ValueType・@components の整合性が崩れ、データがひそかに欠落する原因になります。
2. 既存の .ui ファイルもビルダー経由で読み込んでください — UIBuilder.read(filepath) / .find() / .listEntities() で照会してください。生の JSON を直接 grep／解析しないでください。
   • .ui の直接の Read や、cat / type / Get-Content / rg / grep / sed / awk / cp / mv などのシェルコマンドは、登録済みガードによってブロックされます。読み込みには UIBuilder.read/load/snapshot、書き込みには b.write() を使用してください。.ui ファイル全体を削除するビルダー API はありません。node -e "require('fs').unlinkSync('ui/<File>.ui')" で削除してから refresh を実行してください（シェルの rm / cat はガードによってブロックされます。node -e によるビルダー呼び出しはブロックされません）。
3. Position を直接設定しないでください — anchoredPosition のみを使用してください（Position はエンジンによって管理されます）。
4. 固定アンカー（AnchorsMin == AnchorsMax）で OffsetMin/Max を使ってサイズを指定しながら、anchoredPosition も使用しないでください — 2 つのモードを混在させないでください。
5. ビルダーは新しい UUID を作成しますが、.mlua のプロパティのデフォルト値は更新しません — バインディングが壊れます。

必ず行うこと

1. ビルダーのプロトコルを事前確認 — ../msw-general/references/builder-protocol.md（コア）と ../msw-general/references/builder-protocol-ui.md §3 を、.ui を変更する前に必ずコンテキストに含めてください（このセッションでまだ読み込んでいない場合、またはコンパクションで失われた場合のみ読み込んでください）（UIBuilder API、自動書き込み lint、位置／アンカーのルール、バインディングの注入、カバレッジの不足箇所）。コアには共有契約とビルダー間のフローが記載されています。.map の MapBuilder と .model の ModelBuilder は、兄弟ファイルにある個別のビルダードキュメントを参照してください。各フローが相互に連携しているため、統一されたエントリーポイントを用意しています。
2. ビルダーを呼び出す前に、少なくとも 1 つのデザインガイドを確認してください（ui-fundamentals / ui-hierarchy / component-api §Component Selection Guide）。
3. まずレシピに合うものがないか確認し、ゼロからの構築は最後の手段にしてください。
4. 端への配置には、次の式を使用してください：pos = ±(margin + size/2)
5. ポップアップとトーストは、それぞれ独立した .ui ルート UIGroup に分け、単独で表示／非表示にしてください。内部コンテナーには empty() / panel() を使用し、入れ子の group() は使わないでください。
6. 「中央揃えにしたのに左に寄ってしまう」場合 → テキストに明示的な UpperLeft(0) の配置値が設定されています。MiddleCenter(4) に設定してください。どちらの世代のテキストコンポーネントも、配置のデフォルトは中央揃えです。
7. ボタンのタッチ領域は 88×88 以上にしてください（モバイルサポート）。
8. インタラクティブなボタンを作成したら — references/ui-sound.md を参照して、クリック／ホバー時の効果音を設定するよう積極的に提案してください（デフォルトの UI 効果音 RUID を利用できます）。ユーザーが明示的に辞退した場合、またはボタンが装飾専用の場合に限り、省略してください。
9. ツリーはフラットではなく、入れ子で構築してください。 1 つのまとまりを構成するコントロール（ウィンドウ＋タイトル／閉じるボタン、行＋チップ／値、スロット＋アイコン／数）は、"Parent/Child" パスを使って同じ親の下に置いてください。そうすることで、まとまりとして移動／フェード／表示切り替え／バインドできます。各親を子より先に作成してください。親が存在しないと lint が失敗します（L025 ERROR）。
10. ルートレベルのテキストを、兄弟のボックスに重ねないでください。 ui_lint では L030 WARN として報告されます。テキストをボックスの下にネストする、クリック可能なラベル付きボックスには button() を使用する、または panel() / sprite() の text オプションで直接ラベルを設定してください。

3. サブドキュメント

• references/ui-fundamentals.md — 座標系、RectTransform の 3 要素、アンカーモードの決定（§1～§8）＋解像度・セーフエリア・PC の予約領域・タッチターゲット・フォントサイズ・プラットフォームの分離（§9）
• references/ui-hierarchy.md — UIGroup / displayOrder / CanvasGroup / Enable と Visible の違い
• references/component-api.md — §「コンポーネント選択ガイド」（どれを／いつ／なぜ）＋コンポーネントの全プロパティ・メソッド・イベントテーブル（何があるか）＋UI 関連の全列挙値（§Enums）
• references/layout-recipes.md — レイアウトテンプレート集
• references/runtime-patterns.md — .mlua のランタイムパターン（ポップアップ／トースト／HP／グリッド／ドラッグ…）＋ランタイム UI の注意事項
• references/ui-sound.md — UI サウンドの統合（_SoundService:PlaySound、クリック／ホバーのフック、UI のデフォルト SFX RUID）
• ../msw-general/references/builder-protocol-ui.md §3 — .ui CJS ビルダーの呼び出しプロトコル（統合エントリーポイント — builder-protocol.md のコアと併せて読み込んでください） — .map の MapBuilder / .model の ModelBuilder は、兄弟ファイルとして各ビルダー専用のファイルにあります。panel / text / sprite / button / slider / scroll / script / group / mask / grid / avatar / touchReceive / skeleton / areaParticle / basicParticle、コンポーネントの CRUD、アンカープリセット、書き込み時の自動リンティング、.mlua プロパティ UUID の自動バインドは、すべて §3 と §3.6 にあります。
• references/templates/templates.md — 事前構築済みスタイルバンドルのインデックス（style-N-* .ui、ruid-map.md、Popupbutton.mlua）

4. スクリプト

• scripts/msw_ui_builder.cjs — .ui ビルダーのコア（UIBuilder クラス）。使用前に ../msw-general/references/builder-protocol.md（コア）と ../msw-general/references/builder-protocol-ui.md §3（統合エントリーポイント）を読んでください。
• scripts/preview_ui_layout.cjs — .ui レイアウトの視覚チェック＋タッチターゲットの警告
• scripts/ui_lint.cjs — .ui ファイルの自己検証（write() によって自動的に呼び出されます）
• scripts/ui_recipe.cjs — レシピベースのひな形生成

---

対象外

• .map / .model / .tileset ビルダー — このスキルの対象外です
• .ui JSON スキーマ（生のフィールド形状、@type / @components のラッピング、AlignmentOption 0～15 のマッピングなど）— ビルダー内部で処理されます。ユーザー／AI が直接把握する必要はありません
• アクセシビリティのパターン（代替テキスト、スクリーンリーダー向けのヒント、フォーカス順序）— 対象外です
• エラー状態の UI パターン（Transition.Disabled 以外の無効ボタンのスタイル、検証メッセージ、ローディングスピナー）— 対象外です。プロジェクトごとに個別に設計してください
• ui_lint.cjs と preview_ui_layout.cjs を超える自動 UI テスト／レイアウトアサーション — 提供されません
• カスタムシェーダーマテリアル（MaterialId）— フィールドは公開されていますが、シェーダーの作成はこのスキルの対象外です