msw-general

MSW General — 基盤スキル

MSW（MapleStory Worlds）の制作に必要な共有ツール、ドメイン知識、プラットフォームのルール、ファイル作成を統合した基盤スキルです。他のすべての MSW スキルは、このスキルに依存します。

---

基本原則：ビジュアルの仕上がり

MSW はゲーム制作プラットフォームです。目指すのは、ロジックが動くだけのプロトタイプではなく、プレイヤーが楽しめる完成度の高いゲームです。

そのため、モンスター、NPC、タワー、アイテム、背景オブジェクトなど、どのようなエンティティを作成する場合でも、その役割や個性に合った**リソース（スプライト、アニメーション、サウンド）**を検索して適用してください。デフォルトのスプライトをそのまま使ったり、SpriteRUID を空のままにしたりしないでください。

エンティティ作成時のリソース適用の原則：

1. エンティティを作成したら、msw-search スキルを使って適したスプライトやアニメーションを検索します
2. 見つかったリソースの RUID を SpriteRendererComponent に適用し、エンティティを視覚的に表現します
3. 戦闘がある場合は、ヒットエフェクトや爆発エフェクトも設定します。インタラクションがある場合は、効果音も設定します

**機能を実装しただけでは完成ではありません。**完成度の高いゲームには、適切なリソースと視覚的な演出が必要です。

.model を作成するときは、まずカタログを確認する

空のファイルから新しい .model を作成しないでください。スキル内の models/ フォルダーには、カテゴリ別に整理された検証済みテンプレートがあります。モンスター（ChaseMonster／MoveMonster／StaticMonster）、NPC（StaticNPC）、プレイヤー（Player／DefaultPlayer）、地形（Foothold／Ladder／Rope／Portal）、マップオブジェクト（MapObject／SkeletonMapObject／ItemAsset）、パーティクル（BasicParticle／SpriteParticle／AreaParticle／AnimationPlayer）、サウンド（Sound／SoundEffect）、タイルマップコンテナー（TileMap／RectTileMap）、UI（UIButton／UIText／UISprite／UIGroup など）、外部メディア（WebSprite／YoutubePlayerWorld）があります。

ワークフロー：まず references/model.md を最初から最後まで読む（必須。「Model Work Preflight — MUST」を参照）→ カタログから最も近いテンプレートを選ぶ → ModelBuilder を介して読み込む（呼び出しプロトコル：コアの references/builder-protocol.md ＋ references/builder-protocol-model.md）→ ビルダーを介して 3 つの識別子（EntryKey、Id、Name）を置き換える → ビルダーを介して Components／Values／Properties／Children をカスタマイズする → RootDesk/MyDesk/Models/ の型別サブフォルダーに保存する（例：Models/Monsters/{Name}.model。MyDesk/ 直下には保存しない）→ refresh。詳しいカタログとビルダーの手順：references/model.md §2。

ビルダーが必須の値メタデータを出力するため、エージェントが .model 形式の内部仕様を読んだり、手作業で記述したりする必要はありません。

モンスターの場合は、まず references/animation-state.md §0 でパターンを選び、その後、推奨される方法として references/monster.md §5 に従ってください。

• パターン A（動作確認済みの標準パターン — Soldier のリファレンス設定。ソース全体は references/monster.md §7 にインラインで記載）：テンプレートは不要です。AIChase／AIWander ではなく、カスタムの script.MyMonsterAI（SoldierAI 形式）を使い、11 個のコンポーネントを一から組み立てます。StateComponent.IsLegacy はデフォルトのままにします。
• パターン B（MonsterCanonical.model）：AIChaseComponent ＋ ActionSheet パイプラインを使います。StateComponent.IsLegacy=false は必須です。他のモンスターテンプレート（ChaseMonster／MoveMonster／StaticMonster）は ActionSheet が空で、パターン B では気づきにくい形で失敗するデフォルト設定（大文字のキー、SortingLayer="Default"、IsLegacy=true）を使用しています。

StateAnimationComponent（モンスター／NPC）または AvatarStateAnimationComponent（プレイヤー）を持つエンティティや、ChangeState／AddState／SetActionSheet を呼び出す .mlua を扱う場合は、references/animation-state.md も読んでください。 ステートマシンとアニメーションのパイプライン、2 つのパターンの違い、デフォルトステートの登録ルール、[LEA-3005] の原因、および SetActionSheet と ChangeState のセマンティクスは、エンティティ別ドキュメントには重複して記載せず、ここにまとめています。

---

複数のエンティティの配置 — まずモデルを作成

同じエンティティをマップ内に2回以上配置する場合（モンスター5体、木10本、ポータル3つなど）は、まず.modelを作成し、インラインの@componentsをコピー＆ペーストするのではなく、各インスタンスをmodelIdで配置してください。

同じ構成のインスタンス数	選択肢
1（単一マップにのみ登場する、まったく同じものがない装飾）	インラインの@componentsを使用してもかまいません
≥2	.model + modelIdインスタンス（デフォルト）
実行時にスポーン（SpawnByModelId）	数にかかわらず.modelが必須です

これをデフォルトとする理由：

• 一度編集すれば、すべてに反映 — モデル内のSpriteRUID／HP／ActionSheetを変更すると、すべてのインスタンスが更新されます。インラインのコピーでは、変更のたびにN個のエンティティを修正する必要があります。
• .mapの差分が小さくなり、レビューしやすい — modelIdインスタンスにはTransformの上書きだけが含まれます。インラインコピーでは、エンティティごとに数百行もマップが膨らみます。
• 値の不一致を防止 — インラインコピーを5つ作ると、知らないうちに内容が食い違うことがあります（1つにはIsLegacy: trueが設定され、別のものではSortingLayer: "MapLayer0"が設定されないなど）。モデルによって、正規の値を一元管理できます。
• SpawnByModelIdに必須 — 登録済みのモデルIDがないと、動的なスポーンに失敗します。

ワークフロー：

1. RootDesk/MyDesk/Models/{Category}/{Name}.modelに.modelを作成します（上記のフォルダルールを参照）。
2. MapBuilderを使って各インスタンスを配置します（呼び出しプロトコル：コア + マップ）。これにより、ID、パス、componentNames、原点メタデータ、インスタンスごとのコンポーネント上書きの同期が保たれます。
3. refreshします。

詳細とインライン方式とmodelId方式の比較：references/entity.md "Two-Step Map Editing Workflow"、references/model.md §1。

---

事前読み込みの意味 — このスキル内のすべての「必ず読む」に適用

事前確認や絶対原則における「Xを最初に読む」とは、作業を開始する前にXの内容が完全にコンテキストに含まれている必要があるという意味です。「毎ターンXを再読する」という意味ではありません。ファイルを全文（offset／limitなし、cat／Get-Contentなし）でReadするのは、このセッションで一度も読み込まれていない場合、またはコンテキストの圧縮によって失われた場合に限ってください。すでに全文がコンテキストに含まれているファイルを再読しないでください。必要なのはコンテキスト内に存在することです。再読は無駄です。ファイルのメモや要約は、ファイルがコンテキスト内にあることにはなりません。また、前のターンで読み込んでいても、現在のターンでまだ存在していることを確認する必要があります。

---

エンティティ作業の事前確認 — 必須

タスクに何らかの形でエンティティが関わる場合は、必ず最初にreferences/entity.mdを読んでください。 例外はありません。

Builder Protocol Preflight — MUST

タスクによって .map／.model／.ui ファイルが新規作成または変更される場合（直接の場合も、スポーン／配置／バインドを行う .mlua の記述による副作用の場合も含む）、references/builder-protocol.md（コア）に加え、変更する各ファイル形式に対応するビルダーファイル、つまり references/builder-protocol-map.md（.map）／references/builder-protocol-model.md（.model）／references/builder-protocol-ui.md（.ui）を、まず完全にコンテキストに読み込む必要があります（上記の読み込みの意味を参照）。例外はありません。

このプロトコルは、共通コア（builder-protocol.md — ルーティング、共通ワークフロー、連鎖の契約、§0 事前確認、§4 フロー横断、§5 チェックリスト）と、ビルダーごとのファイル（builder-protocol-map.md §1／builder-protocol-model.md §2／builder-protocol-ui.md §3）に分かれた、統一されたエントリーポイントです。1つのビルダーのプロトコルしか知らずに、別のビルダーの .cjs を呼び出すと、そのビルダーの書き込み側の契約（componentNames の同期、Values の typeKey メタデータ、書き込み時の自動 lint、placeModel のコンポーネントミラーリング、子エンティティの不変条件）を回避することになります。この3つはフロー横断（モデル作成 → マップ配置 → UI バインド）で相互に連携しているため、フロー横断の作業では該当するすべてのビルダーファイルを読み込みます。

トリガー（意図的に広く設定しています。該当するものがあれば、未読のプロトコルファイルを読み込んでください）：

• .map の変更（エンティティ配置、コンポーネントのパッチ適用、タイル／足場の確認）
• .model の変更（新規作成、値／コンポーネント／プロパティ／子要素の編集）
• .ui の変更（新規作成、コンポーネントの CRUD、バインドの挿入）
• MapBuilder／ModelBuilder／UIBuilder の呼び出し
• 「エンティティ形式」の作業にあたる依頼（モンスター／NPC／飛翔体／マップオブジェクト／ポップアップ／HUD など）
• _SpawnService を使用するコード（スポーン可能なモデルは、まず作成して配置する必要があります）

ドメインのリファレンス（entity.md／model.md／msw-ui-system の設計リファレンス）は、プロトコルファイルと併せて読み込みます。これらは代替ではありません（ドメインのコンテキストと呼び出しプロトコルは対になっています）。トリガーが発生する各ターンで、引き続きコンテキストにあることを確認してください。再読み込みするのは、まだ読み込まれていないもの、またはコンパクションで失われたものだけです。

---

Model Work Preflight — MUST

タスクに .model ファイルの作成または編集が何らかの形で含まれる場合（ModelBuilder の呼び出し（あらゆる API）、テンプレートからの新規モデル作成、既存モデルのコンポーネント／値／プロパティ／子要素／イベントリンクの変更、1行だけの修正も含む）、references/model.md をまず完全にコンテキストに読み込む必要があります（上記の読み込みの意味を参照）。例外はありません。

ビルダーのテンプレートカタログ、3つの識別子の置換ルール（EntryKey／Id／Name）、必須の値メタデータ、プロパティ／子要素／イベントリンクの API、および RootDesk/MyDesk/Models/ 配下の型付き保存フォルダー構成は、references/model.md にのみ記載されています。先に references/model.md を読まずにビルダーを呼び出すと、モデルの不具合（値メタデータの欠落、識別子の不一致、誤った保存先フォルダー、デフォルト値のサイレントな失敗）が気づかれないまま発生します。テンプレートファイルを個別に読むことや、記憶を頼りに API を推測することは代わりにはなりません。.model に触れる各ターンの開始時に、引き続きコンテキストにあることを確認し、失われていた場合にのみ再読み込みしてください。

マップ作業前の確認（マップ作業を始める前に実施してください）

マップ関連のタスク（エンティティの配置、スポーン、移動スクリプト、モデルの作成、タイルの編集など）を始める前に、次の2つの手順を順番に必ず完了してください。

1. 対象のマップを特定する — パス（./map/{mapname}.map）、ルートエンティティ、Hierarchy 内での位置を確認します。
2. MapBuilder を使って MapComponent.TileMapMode を数値で読み取る（プロトコル：references/builder-protocol.md の基本部分と references/builder-protocol-map.md）。セッション中はこの値を覚えておいてください。

値	モード	必須の Body	不一致／Body 欠落時のランタイムログ
0	TileMap（MapleTile、サイドビュー＋Foothold）	RigidbodyComponent	[LEA-3004] MissingComponent : Entity is missing 'RigidbodyComponent'.
1	RectTileMap（RectTile、トップダウン）	KinematicbodyComponent	[LEA-3004] MissingComponent : Entity is missing 'KinematicbodyComponent'.
2	SideViewRectTileMap（SideViewRectTile、サイドビュータイル）	SideviewbodyComponent	[LEA-3004] MissingComponent : Entity is missing 'SideviewbodyComponent'.

現在の TileMapMode を把握せずに、マップ作業を始めないでください。 3つのモードでは、Body コンポーネント、重力、衝突、イベントスタックがそれぞれ大きく異なります。不一致がコンパイル時エラーになることはほとんどなく、エンティティが動かない／壁をすり抜ける／表示されないといった無言の失敗、または上記3種類の [LEA-3004] MissingComponent ランタイムログのいずれかとして現れます。これら3つのメッセージのいずれかが表示された場合は、まず TileMapMode とエンティティの Body の不一致を疑ってください。

適切なモードの推奨 — 新しいマップを始めるとき、または現在のモードがユーザーの目的に明らかに合わないときは必須

ユーザーが作成したいゲーム／マップについて説明した場合（新しいマップの作成、「横スクロールゲームにして」「トップダウンのダンジョンが作りたい」など）、または現在の .map を確認して、その TileMapMode がユーザーの意図するゲームプレイに合っていないとわかった場合は、エンティティ／モデル／スクリプトの作業を進める前に、適切な TileMapMode をユーザーにはっきりと推奨し、その理由を説明してください。

次の判断表を正としてください。

ユーザーが意図するゲーム／ゲームプレイ	推奨	理由
MapleStory 風の横スクロールアクション · ジャンプ · はしご · 自由配置の足場（プラットフォーマー）	0 MapleTile	サイドビュー＋重力。FootholdComponent の線分プラットフォームにより、グリッドに縛られず自由に足場を配置できます
トップダウン RPG · 迷路 · ボードゲーム · ダンジョンクローラー · Bomberman 風 · RTS 風 · 農場シミュレーション	1 RectTile	トップダウンの4方向自由移動で、重力はなく、正方形タイルのグリッドを使用します
タイルベースの横スクロールプラットフォーマー · Mario 風のドット絵アクション · サイドビューのパズル（正方形タイルのサイドビュー）	2 SideViewRectTile	タイルグリッド上のサイドビュー＋重力（自由配置の足場ではありません）

手順：

1. ユーザーが作りたいゲームの種類をまだ伝えていない場合は、モードを推奨する前に質問してください（短い質問1つで十分です。例：「トップダウンですか、それとも横スクロール（ジャンプ／はしご）ですか？ また、地形は自由配置の足場を使いますか、それとも正方形のタイルグリッドを使いますか？」）。
2. 意図が明確になったら、推奨するモード（番号＋名前＋1文の理由）と、必要な Body／マップコンポーネントを伝えてください（platform.md §4 の対応表）。
3. 早い段階で選択を確定してください — 後から TileMapMode を切り替えると地形が消去され、すべての Body／移動スクリプトを再確認する必要が生じ、すべてのタイルを塗り直さなければならない場合もあります（platform.md §4「マップタイプ切り替え時の注意事項」）。

TileMapMode の変更 — Maker でのユーザー操作であり、AI によるファイル編集ではありません

AI は .map JSON を直接編集して MapComponent.TileMapMode を絶対に切り替えてはいけません。 モードの切り替えには、タイルコンポーネントの交換、足場の再構築、タイルデータ形式の変換、地形のリセットが必要で、すべて Maker 内部の操作です。

Maker エディターで操作するようユーザーに案内してください：

1. Maker エディターの Hierarchy ウィンドウを開きます。
2. Hierarchy で対象のマップエンティティを右クリックします。
3. コンテキストメニューから、対象モードに対応する「Switch ...」オプションを選択します（Switch TileMap / RectTileMap / SideViewRectTileMap）。Maker が変換を行い、タイルコンポーネントを交換して、必要に応じて地形をリセットします。
4. ユーザーが切り替えの完了を確認したら、MCP の refresh を呼び出し、その後 MapComponent.TileMapMode を再読み込みして変更を確認し、すべての動的エンティティの Body コンポーネントが新しいモードに適合しているか再確認します。

モード変更における AI の役割：提案する → ユーザーが Maker の Hierarchy で右クリックして切り替えるのを待つ → refresh → 適合しなくなった Body コンポーネントやスクリプトを修正する。 ファイル編集で TileMapMode に新しい値を書き込んではいけません。

上の表は概要です。モード切り替えの手順、Body の交換後に行うチェックリスト、LEA-3004 以外のサイレント失敗の症状一覧は、references/platform.md §4（マッピング＋チェック手順＋切り替えポリシー）と references/troubleshooting.md（症状一覧の完全版）にのみ記載されています。モード変更／Body の交換／サイレント失敗のデバッグを行う際は、必ずこれらを読み込んでください。マップタイプごとの詳細パターン：platform-maple.md / platform-rect.md / platform-sideview.md。タイルのペイント：references/tile.md。マップ作業の事前確認：references/entity.md。

---

プラットフォームルールの事前確認 — 次のトリガーに該当する場合は必須

次のトリガーのいずれかがタスクに該当する場合、コードを編集したり計画を提案したりする前に、対応するリファレンスをReadしてください。これらのトリガーは意図的に幅広く設定されています。判断に迷った場合は、リファレンスを読んでください。このSKILL.mdに記載されている「8つのコアルール」は要約にすぎません。症状→原因→修正の表、マップタイプごとのコードパターン、MovementComponentの変換式、SortingLayer／SpriteRUIDの詳細は、リファレンスにのみ記載されています。

トリガー（キーワード／状況）	読むファイル
jump、gravity、movement、MoveVelocity、InputSpeed、JumpForce、WalkSpeed、SpeedFactor、foothold、patrol	該当するマップタイプの references/platform-maple.md／references/platform-rect.md／references/platform-sideview.md（全文）と references/platform.md §10
spawn／_SpawnService／SpawnByModelId／SpawnByEntity／「モンスターを召喚する」／「ランタイム生成」	references/platform.md §8 + §8.5
画面座標／カメラ範囲／「画面に表示されているか」／「ピクセル単位」／OrthographicSize／ワールド単位	references/platform.md §5
遮蔽されている／表示されない／「最前面に表示する」／SortingLayer／OrderInLayer／Z値	references/platform.md §6 + §7
ログにLEA-3004がある／「動かない」／「空中に浮いている」／「壁にはまっている」／「跳ね返される」／「マップ外に消える」／「足場の端から落ちる」	まず**references/troubleshooting.md（全文）**、次に該当するマップタイプのplatform-{type}.md §7
LEA-3005 InvalidArgument 'stateName'／StateComponent／StateType／@State／ChangeState／AddState／AddCondition／ActionSheet／SetActionSheet／StateAnimationComponent／AvatarStateAnimationComponent／StateChangeEvent／「アニメーションが変わらない」／「移動中もstand／idleのまま」／「攻撃ポーズが再生されない」／「被弾アニメーションがループする」／モンスター・NPC・プレイヤーのアニメーション状態に関する作業	まず**references/animation-state.md（全文）**、次にエンティティレベルの構成についてreferences/monster.md（またはエンティティ固有のドキュメント）
shader／material／outline／glow／blur／pixelate／rainbow／tint／grayscale／vignette／screen filter／lens distortion／wave／ripple／distortion／dissolve／additive／blend mode／hologram／mask／post-process／MaterialID／MaterialId／ChangeMaterial／_MaterialService／.materialファイル	references/material.md（全文） — その後、mlua_Document_Retriever + mlua_API_RetrieverのMCP検索を使って、シェーダーカタログ／プロパティ名／コンポーネントごとの互換性を確認してください（記憶に頼らないでください）
新しいマップのセットアップ／新規プロジェクト／.config／セクター登録／フォルダメタデータの更新	references/platform.md §2 + §15
MapleTile（TileMapMode = 0）の作業 — Foothold、Gravity、WalkSpeed、PredictFootholdEnd	references/platform-maple.md（全文）
RectTile（TileMapMode = 1）の作業 — SpeedFactor、4方向移動、移動可能タイル、動的タイル	references/platform-rect.md（全文）
SideViewRectTile（TileMapMode = 2）の作業 — JumpSpeed／JumpDrag、壁検出（Normal）、EnableDownJump	references/platform-sideview.md（全文）

2つ以上のトリガーに該当する場合は、該当するすべてのリファレンスを読んでください。「SKILL.mdの8つのコアルールはすでに確認した」は、リファレンスを読まない理由にはなりません。

8 つの基本ルール（必ず覚えてください）

1. TileMapMode ↔ Body のマッピングが一致していない場合、エンティティは移動しない（エラーなし）か、実行時に [LEA-3004] MissingComponent が発生します → references/platform.md §4（症状から調べる場合は、references/troubleshooting.md）
2. ユーザースクリプトは .mlua と .codeblock のペアでのみ動作します。.codeblock は Maker Refresh によって生成されます。
3. SpriteRUID が空文字列の場合、エンティティは画面に表示されません（エラーなし）。
4. SpawnByModelId を呼び出すとき、マップエンティティ（self.Entity.CurrentMap）を parent として渡さないと、実行時エラーが発生します。
5. 座標の単位はワールド単位です（1 単位 = 100 px）。ピクセル値を使うと 100 倍ずれます。
6. Maker がスキャンするのは RootDesk/ のみです。ユーザーファイルを Global/ に置いても認識されません。
7. .d.mlua または .codeblock は変更しないでください。
8. 手書きのエントリーファイルでは、CoreVersion は Environment/config から取得します。ビルダーの出力ではバージョンを扱う必要はありません。

---

MCP ツール クイックリファレンス（msw-maker-mcp）

ツール	用途
maker_get_current_map	現在のマップ名／ID — セッション開始時に、これらが map/ ファイルの名前とルートエンティティ ID に一致することを確認します（別のワールド上の Maker でも ok と返します）
play / stop	プレイモードの開始／終了
refresh	ファイル変更後に Maker を同期します（プレイ中は実行できません）
logs / clear_logs	実行ログとビルドログの読み取り／消去
screenshot	ユーザーから明示的に要求された場合にのみ呼び出します
keyboard_input / mouse_input	プレイモードでの入力をシミュレートします
maker_execute_script	プログラムによる実行時プローブ — 検証時は、長い入力シミュレーションの連鎖よりもプローブを 1 回実行する方法を優先します（msw-scripting §17）

MCP 呼び出しの失敗／「MCP connection」／「API Key」に関するリクエストがあった場合は、公式セットアップドキュメントを案内してください：https://maplestoryworlds-creators.nexon.com/ko/docs?postId=1368

---

タスク別の参照先 — 読むべきリファレンス

ファイル	対象範囲	読むタイミング
workspace.md	ワールドインスタンス／Room／DataStorage、フォルダー構成、ファイルパス、プレイモード、refresh、ワークフロー途中の失敗からの復旧	ワークスペース／インスタンス／モード遷移に関する作業
platform.md（コア）	8つの基本ルール、ファイルの権威性とフォルダーメタデータ、.mluaと.codeblockのペア、TileMapMode↔BodyのマッピングとLEA-3004、座標系／画面内範囲、SortingLayer/OrderInLayer、SpriteRUID、SpawnByModelIdの使用方法／初期化順序、マップタイプごとのMovementComponentのInputSpeed変換式、ECS、ID生成、.config、CoreVersion	TileMapModeのマッピング／モード切り替え／スポーン／座標／RUID／SortingLayer／.configとCoreVersion／フォルダーメタデータ — すべてのマップタイプに共通するルール
platform-maple.md	MapleTile（TileMapMode = 0）のみ — Footholdの物理、Gravity／WalkSpeed／WalkJump、PredictFootholdEnd、IsOnGround、DownJump、FootholdEnter/LeaveEvent、MapleTile固有のトラブルシューティングとチェックリスト	横スクロールアクション／ジャンプ／はしご／自由に配置できる足場（MapleStory風のプラットフォーマー）
platform-rect.md	RectTile（TileMapMode = 1）のみ — KinematicbodyComponent、SpeedFactor、自由な4方向移動、見た目のみのジャンプ、Movableタイルの衝突、ToCellPosition／ToWorldPosition、RectTileEnter/LeaveEvent、動的タイル（SetTile／BoxFill）、RectTile固有のトラブルシューティングとチェックリスト	トップダウンRPG／迷路／ボードゲーム／ダンジョンクローラー／Bomberman風／RTS／農場シミュレーション
platform-sideview.md	SideViewRectTile（TileMapMode = 2）のみ — SideviewbodyComponent、JumpSpeed／JumpDrag、EnableDownJump、壁の検出（RectTileCollisionBeginEvent＋Normal）、GetUnderfootTile、SideView固有のトラブルシューティングとチェックリスト	タイルベースの横スクロールプラットフォーマー／Mario風のピクセルアクション／横視点パズル
troubleshooting.md	症状別の統合一覧 — LEA-3004の表、「動かない」／「描画されない」／「空中に浮いている」／「壁にはまる」／「マップ外に消える」／「足場の端から落ちる」／「100倍ずれている」／「Makerに表示されない」／「クライアントのみの同期」、その他サイレント障害の症状→原因→修正方法をまとめた索引	症状から始めるデバッグ — ユーザーが上記を報告した場合、またはログに[LEA-3004]が表示された場合は、まずここを確認してください
authoring.md	5種類のファイルに共通するオーサリング原則（スキーマの一貫性、手動編集の危険性）	ファイルをオーサリングする前のエントリーポイント
tile.md	タイルのペイント — Maker UIの領域であり、AIはガイドのみ	タイルマップに関する作業
builder-protocol.md（コア）＋builder-protocol-map.md／builder-protocol-model.md／builder-protocol-ui.md	.map／.model／.uiの統合呼び出しプロトコル — コア：ルーティング、共通ワークフロー、連鎖コントラクト、§0の事前確認、§4のフロー横断事項、§5のチェックリスト、ビルダー別ファイル：MapBuilder §1／ModelBuilder §2／UIBuilder §3のAPI、カバレッジの不足、バインディングの注入	.map／.model／.uiを変更する各ターンで、コアと変更する種類に対応するファイルをコンテキストに含める必要があります（Builder Protocolの事前確認）
entity.md	.mapのエンティティ領域 — Scope、RUID、TileMapModeの事前確認、modelIdとインラインの選択ルール、座標／足場／カメラ、ランタイム検証	.mapの編集／エンティティの配置（呼び出しプロトコルについては、builder-protocol.mdのコアとbuilder-protocol-map.mdを併せて読む）
model.md	.modelのオーサリング領域 — 作成するタイミング、テンプレートカタログ、コンポーネントの組み合わせ、スクリプトコンポーネントのライフサイクル	.modelの作成／編集（呼び出しプロトコルについては、builder-protocol.mdのコアとbuilder-protocol-model.mdを併せて読む）
monster.md	モンスターの標準コンポーネント、小文字のActionSheetキー、必須のIsLegacy／SortingLayerオーバーライド、AIの選択、HP／リスポーン、スポーン位置	モンスターモデルのオーサリング
animation-state.md	StateComponentのデフォルト値と自動登録、状態変更のパイプライン、SetActionSheetとChangeState、StateTypeのオーサリング（サーバーのみ、ParentComponent.Entity）、StateAnimationComponent（モンスター／NPC）とAvatarStateAnimationComponent（プレイヤー）、[LEA-3005]の注意点	モンスター、NPC、プレイヤーの状態／アニメーションに関するあらゆる問題 — エンティティのアニメーションが動作と一致しない場合は、まずここを確認してください
material.md	.materialファイルの構造、シェーダーカテゴリーの索引（10種類以上のカテゴリー）、.model／.map経由またはランタイムのChangeMaterialによるレンダラーコンポーネントへのMaterialIDの適用、_MaterialService:ChangeMaterialProperty（ClientOnly）、およびシェーダーごとのカタログを暗記する代わりに使う、MCPを利用した検索ループ（mlua_Document_Retriever／mlua_API_Retriever）	シェーダー／マテリアル／視覚効果に関するあらゆる作業 — アウトライン、グロー、ぼかし、ビネット、レインボー、ホログラム、ブレンドモード、ポストプロセス、ヒットフラッシュ、画面フィルターなど
msw-ui-systemスキル（Skillツールから呼び出し）	UIの唯一のエントリーポイント。設計上の判断（座標／アンカー／ピボット、UIGroup/CanvasGroup、コンポーネントの選択）＋コンポーネントのプロパティ／メソッド／イベントAPI＋列挙値＋レイアウトレシピ＋mluaのランタイムパターン（ポップアップ／トースト／HP／グリッド／ドラッグ）＋ランタイムUIの注意点＋UUIDバインディング＋.ui CJS UIBuilderの呼び出しプロトコル（パネル／テキスト／スプライト／ボタン／スライダー／スクロール／スクリプト／グループ／マスク／グリッド／アバター／タッチ／スケルトン／パーティクル、アンカープリセット、コンポーネントの追加／置換／パッチ適用／削除、書き込み時の自動リント）	UIに関するあらゆるタスク／.uiファイルの作成や編集 — 最初に読むこと
msw-ui-system/references/templatesファイル	複雑さ別のUI構成パターンテンプレート（シンプルなポップアップ、最小限のHUD、複数タブ、ショップ／購入フロー）。.ui＋.mluaの例とボタンハンドラーのパターンを含む	新しいUIグループ／ポップアップ／HUDの追加、ボタンハンドラーの構成、UIレイアウトパターンの選択（msw-ui-systemの直後に直接読む）
dataset.md	UserDataSet／LocaleDataSetのランタイム、.userdataset＋.csvのペア、_LocalizationServiceはClientOnly、serveronly	データセット／i18n／翻訳

---

絶対原則（すべてのタスクに適用）

0. タスクにエンティティが関係する場合は、まず references/entity.md を読んでください。 例外はありません。 0-bis. ユーザーのリクエストに UI 要素（ポップアップ、HUD、ボタン、トースト、パネル、ダイアログウィンドウ、メニュー、タブ、レイアウト、画面、バー／ゲージ、スロット）への言及がある場合、または .ui ファイルの作成／編集が含まれる場合は、計画、選択肢、質問をユーザーに提示する前に：
   1. まず Skill ツール経由で msw-ui-system を呼び出してください — 設計判断、コンポーネント API、列挙型、レイアウトのレシピ、ランタイムパターン、UUID バインディング、ビルダー呼び出しプロトコルを単一のスキルに統合した、唯一の UI エントリーポイントです。
   2. すべての .ui の変更は msw-ui-system の UIBuilder 経由で行う必要があります — 生の JSON を直接編集したり、grep で検索したりしてはいけません。既存の .ui ファイルも UIBuilder の読み取り API で読み込んでください。（呼び出しプロトコル：references/builder-protocol.md のコア部分 + references/builder-protocol-ui.md §3。）
   3. （任意）UI パターンのテンプレート（シンプルなポップアップ、最小限の HUD、複数タブ、ショップのフロー）が必要な場合は、msw-ui-system/references/templates/ 以下のファイルを直接 Read／Glob してください（templates.md + style-N-*/ + ruid-map.md + Popupbutton.mlua）。 例外はありません。 0-ter. 新しいスクリプトの作成、既存スクリプトの編集、Component／@Logic／@Event／@State／@BTNode の追加・削除、ライフサイクルメソッド（OnBeginPlay／OnUpdate／...）の接続、1 行だけの小さな修正を含め、いずれかの .mlua ファイルを作成、変更、名前変更、削除する場合は、まず msw-scripting/SKILL.md と msw-scripting/references/verify-checklist.md の両方を最初から最後まで必ず Read してください**（offset／limit は使用せず、cat／Get-Content も使用しないでください）。msw-general と、あちこちの .d.mlua ファイルを読むだけでは代わりになりません。前のターンですでに msw-scripting を読み込んでいても、このルールが適用されます — 新しいターンの開始時に必ず再確認してください。トリガーとなる表現は意図的に広く設定されています：このターンで .mlua に触れる可能性が少しでもあれば、トリガーされたものとして扱ってください。例外はありません。「すでに知っている」という理由での省略や、記憶に頼る近道も認められません。 0-quater. スポーン、移動、ジャンプ／重力、座標配置、レイヤー／描画順のデバッグ、MapleTile／RectTile／SideViewRectTile 固有のロジックがタスクに含まれる場合、または無反応な失敗の症状（[LEA-3004] ログ、「動かない」、「描画されない」、「空中に浮いている」、「壁にはまっている」、「マップ外に消える」、「足場の端から落ちる」、「100 倍ずれている」、「Maker に表示されない」、「クライアント側のみ同期される」）が見られる場合は、該当する references/platform*.md／references/troubleshooting.md を必ず事前にすべてコンテキストに読み込んでください**（不足している場合のみ Read — 「事前読み込みの意味」を参照）。さらに、症状がアニメーション／状態に関係する場合（[LEA-3005] ログ、'stateName' is not a valid argument、アニメーションが動作と一致しない、移動中に立ち姿／アイドルのクリップで固まる、攻撃ポーズが再生されない、ヒット演出がループする、カスタム状態がアニメーションしない、StateComponent／StateType／ChangeState／AddState／ActionSheet／SetActionSheet／StateAnimationComponent に触れる内容）は、コードやモデルを編集する前にreferences/animation-state.md を必ず事前にすべてコンテキストに読み込んでください。この SKILL.md にある 8 つの基本ルールは要約にすぎません — 症状→原因→修正の表、マップ種別ごとのコードパターン（足場での巡回、RectTile の 4 方向移動、SideView の壁検出）、MovementComponent の InputSpeed 変換式、SpriteRUID、SortingLayer／OrderInLayer の詳細、SpawnByModelId の初期化順序、フォルダーのメタデータ更新方針、CoreVersion の方針は、参照ドキュメントにのみ記載されています。トリガーとなる表現は意図的に広く設定されています：これらの領域に触れる可能性が少しでもあれば、トリガーされたものとして扱ってください。該当する Read 対象については、上記の「Platform Rules Preflight — MUST」にあるトリガー表に従ってください。例外はありません。「8 つの基本ルールからすでに知っている」という理由での省略や、記憶に頼る近道も認められません。
1. ビジュアルの仕上げ — SpriteRUID を空のままにしないでください。リソースを見つけるには msw-search を使用してください。
2. Maker が取り込む必要のあるコンテンツファイルを変更した後は refresh してください（プレイモード中の場合は、先に stop してください）。フォルダーだけの変更は、すぐに refresh する必要はありません。
3. Environment/*.d.mlua は変更しないでください — API 定義は読み取り専用です。
4. .codeblock を手動で作成しないでください — Maker の refresh が .mlua から生成します。フォルダーのメタデータも refresh 時に実際のフォルダーから生成されます。
5. Global/ に新しいユーザーファイルを作成しないでください — Maker が認識しません。ユーザーファイルは RootDesk/MyDesk/ 以下に置いてください。
6. 構造化ファイルではビルダーを優先します。呼び出しマニュアルは、共通コアとビルダー別ファイルで構成される、統合された唯一のエントリーポイントです — .model／.ui はビルダーのみを使用し、.map はビルダーを優先します。3 つすべてのビルダー — MapBuilder／ModelBuilder／UIBuilder — の呼び出しプロトコルは、references/builder-protocol.md（コア）と、ビルダー別ファイル（builder-protocol-map.md／builder-protocol-model.md／builder-protocol-ui.md）に集約されています。.map／.model／.ui を変更するターンでは、コアと、変更する型に該当するファイルを必ずコンテキストに読み込んでください（Builder Protocol Preflight を参照）。生の JSON を直接編集できるのは、ビルダー別ファイルに明記された対応範囲の不足部分に限られます — 対象を最小限にし、refresh を行い、ログを検証してください。
7. エンティティ参照のバインディング（Entity／EntityRef プロパティ） — AI が UUID 文字列を直接注入します。Maker でドラッグするようユーザーに依頼しないでください。
8. ユーザーが明示的に依頼した場合に限り screenshot を呼び出してください。 タスク完了後に自動で呼び出してはいけません。
9. ワークフローの途中で手順が失敗した場合は、後続の手順を停止してください — まず根本原因を修正してください。
10. 同じものが 2 つ以上ならモデルを作成します。 同じエンティティ構成をマップに 2 回以上配置する場合は、まず .model を作成し、modelId を介してインスタンス化してください。インラインの @components の重複は、実際に 1 回だけ使用するエンティティに限ります。
11. モデルは型別サブフォルダーに保存します。 新しい .model ファイルは RootDesk/MyDesk/Models/ のカテゴリ別サブフォルダー（例：Models/Monsters/、Models/NPCs/、Models/Terrain/、Models/MapObjects/、Models/Particles/、Models/UI/）に保存してください — MyDesk/ や Models/ の直下には決して保存しないでください。必要なサブフォルダーが存在しない場合は、フォルダーだけを作成してください。Maker Refresh によって、後でフォルダーのメタデータが生成されます（references/platform.md §2 を参照）。
12. 翻訳はクライアント側のみで行います。 _LocalizationService と Translator のメソッド（GetText／GetTextFormat）はすべて ClientOnly です。サーバーからローカライズされたメッセージを送る場合は、キーを RPC で送信し、クライアント側で解決してください。
13. クロスプラットフォームでのツール選択 — ワークスペースの調査にはシェルを使わず、ツールを使用してください。 ワークスペース内のすべてのファイル／フォルダーの調査、読み込み、検索には、Glob／Read／Grep ツールを使用してください。ls／dir／Get-ChildItem／gci／cat／type／Get-Content／gc／head／tail／find／where／grep／findstr／Select-String などの Bash コマンドは、ワークスペースの調査には使用禁止です — Windows（PowerShell／Git Bash）と macOS（bash／zsh）で互換性がなく、シェル／パスの処理に違いがあるためです（特に bash では、D:\path\foo のようなパスのバックスラッシュがエスケープとして消費され、D:pathfoo に変わります）。Bash は実際のシェルプログラム（git／npm／MCP／ビルドスクリプト）に限って使用し、その場合も：（a）ワークスペース相対パスを優先する、（b）絶対パスが避けられない場合はスラッシュと二重引用符を使用する（"D:/path/to/map/" のようにし、D:\... 形式は決して渡さない）、（c）POSIX コマンドのみを使用する（ls／mv／cp／rm）。ls: cannot access 'D:path...': No such file or directory のようなエラーが出た場合は、すぐに中断し、Glob／Read で再試行してください。
14. .model ファイルはビルダーのみを使用し、ビルダーを使う前に references/model.md（ドメイン）と references/builder-protocol.md（コアの呼び出しプロトコル）、references/builder-protocol-model.md（モデルの呼び出しプロトコル）が必要です。 .model の JSON を直接調べたり編集したりしないでください。ModelBuilder を使用する前に、これらのドキュメントをすべて最初から最後までコンテキストに読み込んでください（上記の読み込みルールを参照）— 「Model Work Preflight」と「Builder Protocol Preflight」の両方が適用されます。識別子、値のメタデータ、プロパティ、子要素、イベントリンクの整合性は、これらをすべてまとめて読んだ場合にのみ保証されます。
15. .map ファイルではビルダーを優先します。 対応している調査と変更には MapBuilder を使用し、エンティティ ID、パス、コンポーネント名、起点のメタデータ、モデルインスタンスのミラーの整合性を保ってください。必要な操作が MapBuilder の明示的な対応範囲外である場合は、.map を直接編集する範囲を最小限にし、その後 refresh を実行して検証してください。完全な API／require パス／操作ごとのパターン／対応範囲外の操作／false 返却時の処理／クロスフロー：references/builder-protocol-map.md §1 + references/builder-protocol.md §4（ドメインのコンテキストについては references/entity.md と併せて読んでください）。