msw-search

MSW 検索

MSW には異なる検索対象が 2 つあります。

1. API ドキュメントと実装ガイド — .d.mlua に不足している説明、コード例、関連 API を対象にしたベクトル検索です。
2. リソース — スプライト、アニメーション、サウンド、リソースパック、アバターを対象とした REST API です。RUID を取得する唯一の手段です。

---

ルーティング表

リクエストの種類	参照するセクション
「これを実装するには？」「例を見せて」「関連する API は何がありますか？」	ドキュメント検索
「.d.mlua にはシグネチャしかなく、説明が不十分です」	ドキュメント検索
「API 名がわかりません（セマンティック検索）」	ドキュメント検索
「実装ガイド／ベストプラクティス／パターン」	ドキュメント検索
「SpriteRUID が必要です」「モンスター／NPC／背景のスプライトを探して」	リソース検索 → resource_pack から開始
「アニメーション／サウンド／リソースパックを探して」	リソース検索 → resource_pack から開始
「この RUID の詳細」「類似するリソース」	リソース検索
「アバターアイテム／デフォルトアバターの検索」	リソース検索
「自分のアセットをアップロード／一覧表示／更新／削除」	msw-mcp の asset_* ツールを直接呼び出す
「スプライトのピボットを設定」「9 スライスの境界を設定」「UI RUID のスライス境界」「アセットプロパティ」	msw-mcp の asset_update_resource_storage_info を直接呼び出す（properties: [{ key, value }] — pivot_x/y、border_left/right/top/bottom、filter_mode、wrap_mode）

★ リソース検索のデフォルト — 必ず resource_pack から開始

ユーザーが個別のスプライト／animationclip／サウンド／アバターアイテムを明示的に求めている場合（またはパック以外の RUID を直接指定している場合）を除き、searchResources に resourceTypeFilter: ["resource_pack"] を渡してください。1 つのアセットのすべてのスプライト＋アニメーション＋サウンドがパックにまとめられているため、先に個別の sprite や animationclip を選ぶと、エンティティにフレームが 1 つしか含まれない、アニメーションセットがない、または誤ったアセットファミリーが選ばれることがよくあります。

パックを検索 → payload.elements を調べる → 個別の RUID を割り当てます。 タイプを切り替えるのは、「BGM ファイル」「個別のスプライトのみ」「アバターアイテム」「この RUID に類似する animationclip」など、意図が明示されている場合に限ります。

---

セクション 1 — ドキュメント検索（API とガイド）

msw-mcp MCP サーバーを介したベクトル検索です。.d.mlua に不足している詳細な説明、コード例、関連 API、実装ガイドを提供します。

判断フロー

Need API-related information
│
├─ Checking signature / type / property / enum
│   → Read .d.mlua first (highest priority)
│   → If .d.mlua is insufficient, call msw-mcp
│     (code examples, parameter details, related APIs, etc.)
│
├─ Implementation guide / pattern / best practice
│   → mlua_document_retriever
│
└─ Don't know the API name (semantic search)
    → mlua_api_retriever (and/or mlua_document_retriever for broader scope)

---

API の調査順序

優先度 1 — .d.mlua（必ず最初に確認）

API 名がわかっている場合は、必ず最初に .d.mlua を読みます。 シグネチャ、型、プロパティ、イベントパラメーター、列挙型の値を正確に確認できます。

パス：Environment/NativeScripts/{Component,Service,Event,Enum,Logic,Misc}/Name.d.mlua

状況	例
メソッドのシグネチャを確認する	「TransformComponent に SetPosition はありますか？」
プロパティの型／存在を確認する	「SpriteRendererComponent.RUID の型は何ですか？」
イベントパラメーターの構造を確認する	「AttackEvent コンストラクターのパラメーターは何ですか？」
列挙型の値を一覧表示する	「BodyMoveType の値は何ですか？」
メソッドの存在を確認する	「SpawnService にはどのようなメソッドがありますか？」

優先度 2 — ベクトル検索（.d.mlua だけでは不十分な場合）

.d.mlua にはシグネチャのみが含まれており、詳細な説明や例はありません。 次のいずれかが必要な場合は、ベクトル検索を使用してください。

状況	MCP ツール	クエリ例
コード例が必要	mlua_api_retriever	AIComponent example、BehaviorTree usage
パラメーターの詳細	mlua_api_retriever	BadgeService GetBadgeInfosAndWait parameters
関連 APIの相互参照	mlua_api_retriever	AttackComponent related、HitComponent
ScriptOverridable の確認	mlua_api_retriever	AttackComponent CalcCritical override
API 名がわからない	両方のリトリーバー	damage calculation、inventory save
**「どうすれば…できますか？」**という実装ガイド	mlua_document_retriever	how to make inventory system
パターン／ベストプラクティス	mlua_document_retriever	collision detection best practice

---

MCP ツール（msw-mcp）

ツール	説明
mlua_api_retriever	Service／Component／Misc などの API 詳細（シグネチャ、パラメーター、例）。API／クラス／関数／コンポーネント名を渡します。
mlua_document_retriever	作成マニュアル、ガイドライン、MLua の使用方法、その他のドキュメント形式の資料。実装したい内容を説明する自然言語の文を渡します。

失敗時：msw-mcp ツール呼び出しでエラーが発生した場合は、失敗したことをユーザーに伝え、.d.mlua にフォールバックしてください。推測せず、確認できなかった内容を明示してください。

デフォルトの結果件数：より広範な調査が明示的に必要でない限り、結果を 3 件リクエストしてください。

---

.d.mlua と検索 — 情報の比較

.d.mlua は型スタブ（約 29 行）です。検索ではドキュメント全文（254 行以上）が返されます。

情報	.d.mlua	検索
メソッドのシグネチャ／型	O	O
プロパティの宣言	O	O
メソッドの詳細な説明（DetailDesc）	X	O
コード例（AdditionalPageContent）	X	O
パラメーターごとの説明	X	O
関連 API（SeeAlsoAPIs）	X	O
関連ガイド（SeeAlsoGuides）	X	O
ScriptOverridable フラグ	X	O
SyncDirection	一部	O
ローカライズされた説明（Ko/Ja/Es/Zh）	X	O

---

Maker Editor 構文 → .mlua 変換ルール

検索結果のコード例ではMaker Editor 構文が使われています。ローカルの .mlua ファイルで使用する前に変換する必要があります。

項目	Maker Editor	.mlua ファイル	備考
オーバーライド宣言	override integer CalcDamage(...)	method integer CalcDamage(...)	override → method
ブロック	{ ... }	... end	波括弧 → end
実行スペース（独自メソッド）	[server only]	@ExecSpace("ServerOnly")	独自定義メソッドでは明示的に注釈を付けます
実行スペース（オーバーライド）	エディターでは [server only] が表示される／省略される	親の @ExecSpace と完全に一致させます — 以下の警告を参照	不一致の場合は LEA-3014
プロパティ	Property: int32 Score = 0	@Sync property int32 Score = 0	同期する場合は @Sync を追加します
型 int	int	integer	C# の int → mlua の integer
型 number	number	number	同じ（double）
型 float	float	float	同じ（single）

number（64-bit double）と float（32-bit single）は互いに代入できますが、別個の型です。.d.mlua の宣言に従ってください。

⚠ オーバーライドの ExecSpace に関する注意 — LEA-3014 SignatureMismatch

Maker Editor では、親の実行スペースが非表示になっていることが多く、override ブロックの [server only] を自由に切り替えられます。しかし .mlua では、オーバーライドの @ExecSpace は .d.mlua で宣言された親のものとバイト単位で完全に一致している必要があります。親に @ExecSpace がない場合（エンジンのデフォルトは ExecSpace=All）、オーバーライドでも @ExecSpace を完全に省略する必要があります。

具体的には、AttackComponent / HitComponent のダメージフック（CalcDamage、CalcCritical、GetCriticalDamageRate、GetDisplayHitCount、IsAttackTarget、IsHitTarget、OnAttack）は、すべて上流で ExecSpace=All です。@ExecSpace("ServerOnly") を追加すると、次のエラーが発生します。

[LEA-3014] SignatureMismatch : The signature of <Child>.CalcDamage[... (ExecSpace=ServerOnly)]
  must match the overridden <Parent>.CalcDamage.[... (ExecSpace=All)].

必ず最初に .d.mlua で親を確認し、その注釈ブロックをそのままコピーしてください。詳細は msw-scripting/SKILL.md §9 "Method override → LEA-3014" を参照してください。

変換例 — 検索結果の AttackComponent：

-- Maker Editor syntax (search result)
override int CalcDamage(Entity attacker, Entity defender, string attackInfo) {
    return 50
}
override boolean CalcCritical(Entity attacker, Entity defender, string attackInfo) {
    return _UtilLogic:RandomDouble() < 0.3
}

-- Converted to .mlua
-- ⚠ Parent AttackComponent.CalcDamage / CalcCritical declare no @ExecSpace
--   (ExecSpace=All). Adding @ExecSpace here triggers LEA-3014 SignatureMismatch.
method integer CalcDamage(Entity attacker, Entity defender, string attackInfo)
    return 50
end

method boolean CalcCritical(Entity attacker, Entity defender, string attackInfo)
    return _UtilLogic:RandomDouble() < 0.3
end

---

セクション 2 — リソース検索（スプライト／アニメーション／サウンド／リソースパック／アバター）

MSW リソースを検索・閲覧する REST API です。 RUID を推測したり捏造したりしないでください — 必ずこの API から取得してください。

デフォルトの検索タイプ = resource_pack — 上記のルーティングテーブルにあるパック優先ルールを参照してください。

アクセス — 必ず msw_resource_api.cjs を使用してください

このスキルでのリソース API 呼び出しはすべて、次の Node.js ラッパー経由で行います。

scripts/msw_resource_api.cjs

curl コマンドを手作業で組み立てないでください。 このラッパーには次の特長があります。

• UTF-8 の JSON ボディを直接送信するため、非 ASCII のクエリ（韓国語／日本語／中国語／絵文字）でも、インラインの curl -d '...' で発生する {"detail":"There was an error parsing the body"} エラーを回避できます。
• スラッシュを含むパスパラメーター（npc/1013617.img のようなパック ID など）を URL エンコードします。
• 依存関係はありません（Node 18+ に組み込まれた fetch／AbortController を使用）。
• OpenAPI の正確なフィールド名（topK、resourceTypeFilter、categoryFilter、count、…）を使用します。limit／types／categories などの古い名前は、サーバーによって警告なしに無視されます。

使用方法は 2 通りあります。

# 1) CLI — fire one call from a shell. Output is pretty-printed JSON.
node scripts/msw_resource_api.cjs \
    search "orange mushroom" --resource-type resource_pack --category npc --topK 3

# Discover available subcommands:
node scripts/msw_resource_api.cjs --help

// 2) require — preferred when already in a Node.js context.
const {
  searchResources, searchAvatarItems, findSimilarResources,
  getResource, getResourcesBatch, getResourceTags,
  listResources, randomResources, findPacksContaining,
  listAvatars, getAvatarDefaults,
} = require('./scripts/msw_resource_api.cjs');

const result = await searchResources("orange mushroom", {
  resourceTypeFilter: ["resource_pack"],
  categoryFilter: ["npc"],
  topK: 3,
});

ラッパー関数 ↔ エンドポイント対応表

ラッパー関数	CLI サブコマンド	エンドポイント
searchResources	search	POST /v3/search/resources
searchAvatarItems	search-avatar	POST /v3/search/resources（アバターモード）
findSimilarResources	similar	GET /v3/search/resources/similar/{ruid}
getResource	get	GET /v3/resources/{ruid}（sprite / animationclip / resource_pack / avataritem で動作します）
getResourcesBatch	batch	POST /v3/resources/batch
getResourceTags	tags	GET /v3/resources/tags/{ruid}
listResources	list	GET /v3/resources（Qdrant Scroll、不透明な文字列の offset カーソル）
randomResources	random	GET /v3/resources/random
findPacksContaining	packs	GET /v3/resources/packs/{ruid}（RUIDを含むパックを一覧表示します — ここではパックIDは受け付けられません）
listAvatars	avatars	GET /v3/avatars
getAvatarDefaults	avatar-defaults	GET /v3/avatars/defaults

/v3/avatars/{ruid} エンドポイントは存在しません。 avataritem （color_hex、グループメンバーなど）を確認するには、getResource(ruid) を呼び出してください。 /v3/resources/{ruid} エンドポイントは、ほかのリソースと同様に avataritem の詳細を返します。

ベース URL とトランスポート（参考情報）

これらはすべてラッパーが処理するため、手動で設定する必要はありません。

• ベース URL：https://maplestoryworlds-resourcesearch-new.nexon.com/api
• 認証なし（公開）、/v3/ プレフィックス、POST ボディは application/json; charset=utf-8
• デフォルトのタイムアウト：15s（ラッパーの _request(method, path, { timeout }) で変更できます）

結果件数 — このスキルのデフォルトは 3 です

特に指示がない限り、すべての検索呼び出しで結果件数パラメーターには 必ず 3 を指定してください。ラッパーのデフォルトも 3 であり、パラメーター名は OpenAPI 仕様に正確に準拠しています。エンドポイントによって limit / count / topK が異なる点に注意してください。

エンドポイント	サーバーパラメーター	ラッパーのデフォルト
POST /v3/search/resources（リソース + アバター）	topK	3
GET /v3/search/resources/similar/{ruid}	topK	3
GET /v3/resources（ブラウズ）	limit	3
GET /v3/resources/random	count	3
GET /v3/resources/packs/{ruid}（RUIDを含むパック）	limit	3

サーバー側のデフォルトは 20 または 50 なので、これらのパラメーターは必ず明示的に指定してください。 より広範な探索が明示的に必要な場合に限り、10 以上（アバターの幅広いブラウズでは 50〜100）に増やしてください。

offset パラメーターに関する注意 — GET /v3/resources と GET /v3/resources/packs/{ruid} では、 offset は整数ではなく、前のレスポンスで返される不透明な文字列カーソル nextOffset です。 1 ページ目では送信しないでください（整数の 0 を送信するとカーソルとして解釈され、結果が空になります）。

POST ボディのルール — msw_resource_api.cjs に任せてください

ラッパーを使わずに POST する必要がある場合（使用言語に HTTP クライアントがない場合）は、次の動作を再現してください。

1. ボディをUTF-8 の JSON バイト列としてシリアライズします（再エンコードされたシェル文字列ではありません）。
2. Content-Type: application/json; charset=utf-8 を送信します。
3. 生のバイト列を POST します（例：curl の --data-binary "@file" で UTF-8 の一時ファイルを読み込みます）。

それ以外の場合は、ラッパーを呼び出してください。

リソースタイプ

type の値（サーバーレスポンスの type フィールド、および検索時に resourceTypeFilter 配列に指定する値）：

type	説明
sprite	静止画像（PNG）
animationclip	フレームベースのアニメーション
resource_pack	スプライト、アニメーション、サウンドをまとめた完成済みアセットパック
bgm	BGM（音声）
voice	ボイスクリップ — NPC のセリフなど（音声）
effect	効果音（音声）。 視覚効果ではありません。視覚的なパーティクル／ヒット／スキル FX を探す場合は、sprite または animationclip（カテゴリ skill／mob／etc）を検索してください。
avataritem	アバターのコスチュームアイテム（帽子、コート、パンツ、靴、武器など） — resourceTypeFilter: ["avataritem"] を指定し、同じ POST /v3/search/resources エンドポイントを使用します。references/resource/search.md（「アバターアイテムの検索」）および references/resource/avatar.md を参照してください。

検索および一覧表示のすべてのエンドポイントでは、同じタイプフィルターフィールド名 resourceTypeFilter （配列）を使用します。types などの別の名前はサーバーによって無視されます。 ラッパーの resource_type_filter 引数（または CLI の --resource-type）は、このフィールドに対応します。

⚠ SpriteRendererComponent.SpriteRUID は sprite と animationclip の両方を受け付けますが、描画方法は異なります：

• animationclip → すべてのフレームレイヤーが再生されます（影 + 本体 + 前景）
• sprite → その単一の Sprite のみが描画されます

間違えた場合の症状：sprite を指定するつもりで animationclip の RUID を渡す（またはその逆）と、影のレイヤーだけが表示され、本体がいつの間にか消えます。SpriteRUID に割り当てる前に、必ずレスポンスの payload.type を確認してください。静止した待機／デフォルトフレームには sprite を使用し、animationclip は StateAnimationComponent.ActionSheet の値などのフィールドにのみ使用してください。

skeleton と avataritem の RUID は、thumbnail:// プレフィックスを付けずに SpriteRUID／ImageRUID に割り当てると、エラーもなく何も描画されずに失敗します。 反対に、CostumeManagerComponent.Custom*Equip／SkeletonRendererComponent.SkeletonRUID／StateAnimationComponent.ActionSheet は thumbnail:// プレフィックスを受け付けません。ここにはプレーンな RUID を渡してください。検索クエリがアイコン／サムネイル画像を対象としていて、sprite の RUID が返された場合、その RUID はすでに直接描画できるため、thumbnail:// を追加する必要はありません。割り当てルールの全容 — 受け入れられるタイプ、スロットごとのプレフィックス対応表、RUID とプレフィックスの使い分け — は msw-sprite-ruid/SKILL.md に記載されています。

カテゴリ

レスポンスに実際に含まれる category の値です。categoryFilter と併用してください。

一般リソース（sprite／animationclip／resource_pack／bgm／voice／effect）

category	説明
mob	モンスター
npc	NPC
item	アイテム
skill	スキル効果／スキルリソース
object	マップオブジェクト（木、岩、装飾）
background	背景／マップタイル／BGM
foothold	歩行可能な足場
rope	ロープ
ladder	はしご
etc	分類なし

アバター（avataritem のみ）

category	スロット
cap, hair, face, faceaccessory, eyeaccessory, earaccessory	頭／顔
coat, longcoat, pants, shoes, glove, cape	体
weapon, twohandweapon, subweapon, shield	武器

map、effect、ui は有効なカテゴリ値ではなく、検索結果は 0 件になります。

• マップ／背景を探す場合 → category: "background" または "object" を指定してください。
• 視覚効果を探す場合 → category: "skill"（または mob／etc）を指定して sprite／animationclip を検索してください。effect はカテゴリではなく、音声のリソースタイプです。
• このインデックスには ui のリソースファミリーはありません。UI スプライトは通常、sprite + category: "etc" として登録されています。

RUID

各リソースを一意に識別する32文字の16進数文字列です。例："0017da7385e04bc4b2ddbe5949b4b462"

• 検索結果のidフィールドがRUIDです
• assetGuidは別のUnityアセットGUIDです（spawn_presetで使用）
• RUIDを推測したり捏造したりしないでください。必ずAPIレスポンスから取得してください

共通レスポンスフィールド

{
  "id": "32-char hex RUID",
  "type": "sprite|animationclip|resource_pack|bgm|voice|effect|avataritem",
  "category": "mob|npc|item|skill|object|background|foothold|rope|ladder|etc | <avatar slot>",
  "names": {
    "ko": ["Korean name"],
    "en": ["English name"]
  },
  "assetGuid": "Unity asset GUID (may or may not exist)",
  "payload": {
    "width": 64,
    "height": 64,
    "thumbnail": "https://...",
    "pivot": {"x": 32, "y": 32},
    "frames": [],
    "elements": []
  }
}

ページネーション — 同じ名前、2つの形式

nextOffsetはすべてのリスト形式のレスポンスに含まれますが、エンドポイントによって意味が異なります。値を誤ったエンドポイントにそのまま渡すと、エラーなく誤動作します。

エンドポイント	nextOffsetの型	意味	ページネーション方法
POST /v3/search/resources（検索）	整数	アイテムのオフセット（0始まり）	offsetとして（数値で）渡します
GET /v3/search/resources/similar/{id}（類似検索）	整数	アイテムのオフセット	同様
GET /v3/resources（リスト）	不透明なUUID文字列	Qdrantのスクロールカーソル	文字列をoffsetとして渡します。ストリームの終端はnullです
GET /v3/resources/packs/{ruid}（パック）	不透明なUUID文字列	同じカーソル	同様
GET /v3/resources/random	該当なし	ページネーションなし	—

ルール：

1. listのカーソルをsearch呼び出しに（またはその逆に）渡さないでください。サーバーは形式が異なる値を無視し、最初のページを返します。
2. 最初のページでは、offsetを完全に省略してください。list／packsに整数の0を送るとカーソルとして解釈され、アイテムが0件返されます（エラーなし）。
3. レスポンスのnextOffset: nullが返されたとき（list／packs）、またはtopKより少ないアイテムが返されたとき（search／similar）に、ページネーションを終了してください。

エンドポイントの概要

メソッド	エンドポイント	用途
POST	/v3/search/resources	自然言語によるセマンティック検索（resourceTypeFilter: ["avataritem"]でアバターアイテムも検索可能）
GET	/v3/search/resources/similar/{ruid}	類似リソースを検索
GET	/v3/resources/{ruid}	単一リソースの詳細（sprite／animationclip／要素が設定済みのresource_pack／avataritem）
POST	/v3/resources/batch	複数のリソースを一括取得
GET	/v3/resources/tags/{ruid}	AI生成の多言語タグ
GET	/v3/resources	リソースの一覧（Qdrantスクロール、不透明な文字列のoffsetカーソル）
GET	/v3/resources/random	ランダムなリソースのおすすめ
GET	/v3/resources/packs/{ruid}	指定したRUIDを含むリソースパックの一覧 — パスパラメーターは32文字の16進数のRUIDであり、パックIDではありません
GET	/v3/avatars	すべてのアバターアイテムを一覧表示（キャッシュ済み）
GET	/v3/avatars/defaults	デフォルトのアバターのボディ／ヘッドRUID

単一のavataritemの詳細には/v3/resources/{ruid}を使用します（ /v3/avatars/{ruid}エンドポイントは存在しません）。

---

リソースのルーティングガイド

★ 迷ったら、まず resource_pack を検索してください。 以下で明示的にパック以外の意図が示されている行のみ、パックを最初に検索するという既定の手順を省略できます。

状況	ラッパー呼び出し（CLI サブコマンド）	参照ファイル
「スライム／オレンジ色のキノコ／モンスター／NPC／アイテム／背景／マップアセットを探す」（既定 — 種類の指定なし）	searchResources(query, { resourceTypeFilter: ["resource_pack"], ... })（search ... --resource-type resource_pack）	references/resource/search.md
「個別のスプライト／単一の画像を探す」（ユーザーが明示的にスプライトを指定）	searchResources(query, { resourceTypeFilter: ["sprite"], ... })	references/resource/search.md
「個別のアニメーションクリップを探す」（ユーザーが明示的にアニメーションを指定）	searchResources(query, { resourceTypeFilter: ["animationclip"], ... })	references/resource/search.md
「視覚効果／パーティクル／ヒットエフェクトを探す」	searchResources(query, { resourceTypeFilter: ["animationclip","sprite"], categoryFilter: ["skill","mob","etc"] }) — ここで effect は視覚効果ではなく音声を意味します	references/resource/search.md
「サウンド／BGM／音声／効果音を探す」（音声）	searchResources(query, { resourceTypeFilter: ["bgm"|"voice"|"effect"], ... }) — effect の resource_type は効果音（音声）です	references/resource/search.md
「背景／マップタイル／風景を探す」	searchResources(query, { resourceTypeFilter: ["sprite","animationclip"], categoryFilter: ["background","object"] }) — インデックスには map カテゴリーはありません	references/resource/search.md
「コスチューム／帽子／靴／武器を探す」（アバターアイテム）	searchAvatarItems(...)（search-avatar）	references/resource/search.md（アバターアイテム検索セクション）＋ references/resource/avatar.md
「このモンスターに似たものはほかにありますか？」	findSimilarResources(ruid, ...)（similar）	references/resource/search.md
「RUID abc123 の詳細」（アバターアイテムや resource_pack を含むすべての種類）	getResource(ruid)（get）	references/resource/detail.md
「モンスターのスプライト一覧を表示する」	listResources(...)（list）	references/resource/browse.md
「この RUID を含むリソースパックはどれですか？」	findPacksContaining(ruid, ...)（packs）	references/resource/browse.md
「すべてのアバターアイテムを閲覧する」	listAvatars(...)（avatars）	references/resource/avatar.md

典型的なワークフロー（パックを最初に検索）

1. searchResources(query, { resourceTypeFilter: ["resource_pack"], topK: 3 })
   → obtain a resource_pack RUID (or pack id like "npc/9072309.img")
   → switch types only on explicit user intent, or fall back when 0 packs match
2. getResource(id)
   → resource_pack: payload.elements is pre-populated with element payloads
                    (sprite / animationclip / sound RUIDs live here)
   → avataritem:    payload has color_hex / group meta
3. Pick the element from payload.elements and assign its RUID to
   SpriteRendererComponent.SpriteRUID / StateAnimationComponent.ActionSheet
   (or assign avataritem RUIDs through the slot mapping in `msw-avatar`)

findPacksContaining(packId) をパックの「表示」に使わないでください。 このエンドポイントは 32 桁の 16 進数の RUID を受け取り、その RUID を含むパックを返すものであり、パックの内容は返しません。パックの内容を取得するには getResource(packId) を使用してください。

各エンドポイントのリクエスト／レスポンスの詳細については、references/resource/ 配下のファイルを参照してください。

---

スプライトの向き — ほとんどのリソースは左向きです

MSW のスプライト／アニメーションクリップ／resource_pack アセットのほとんど、特に mob、npc、プレイヤーキャラクターは左向きで作成されているため、生成直後の SpriteRendererComponent は、反転しない限り左向きに描画されます。

状況	対応方法
右向きにしたいエンティティを生成する	SpriteRendererComponent の FlipX = true を設定します（デフォルトは false で、作成時の向きである左向きです）
MovementComponent:MoveToDirection を使ったカスタム AI／追跡	方向が変わったときに FlipX を更新します：sprite.FlipX = velocity.x > 0（右向き ⇒ 反転）
モンスターのモデル／モンスターのコライダーの位置合わせ	FlipX の代わりに TransformComponent.Scale.x を反転させ、スプライトとコライダーの位置を合わせます。詳しくは msw-general/references/monster.md を参照してください
ネイティブの AIChaseComponent ／ AIWanderComponent	エンジンが移動に応じて自動的に反転するため、何もする必要はありません
トップダウン（RectTile）移動	軸ごとに判断します。通常は dx > 0 のときに反転します。上下のフレームがあるスプライトでは、代わりに StateAnimationComponent のアクションセットが必要です
_EffectService:PlayEffect(...) を右向きにする	options テーブルに FlipX = true を渡します
プレイヤーに付随するエフェクトをプレイヤーの向きに追従させる	PlayEffect のオプションで SyncFlip = true を使うか、PlayerControllerComponent.LookDirectionX を読み取ります
リソースが右向きで作成されている（まれ）	GET /v3/resources/{ruid} で payload.thumbnail を確認し、そのアセットではルールを逆にします

-- Custom side-view chase: flip sprite to match movement direction
local sprite = self.Entity.SpriteRendererComponent
local selfX = self.Entity.TransformComponent.WorldPosition.x
local dx    = targetPos.x - selfX
if dx ~= 0 then
    sprite.FlipX = dx > 0   -- target on the right → flip
end

確認事項 — 左向きという規則は契約上保証されていません。GET /v3/resources/{ruid} から payload.thumbnail を開いて確認してください。

一般的なレンダラーの反転に TransformComponent.Scale.x を使わないでください — プレイヤー／エフェクト／モンスター以外のレンダラーでは、SpriteRendererComponent.FlipX を使います。モンスターの場合：スプライトとコライダーの位置を合わせるため、モンスターのモデルでは TransformComponent.Scale.x を反転させてください。関連資料：msw-combat-system/SKILL.md "Direction check ★"、msw-general/references/monster.md。

---

共通のヒント

1. キーワードの選択 — 名前が分かっている場合は正確な名前を使います。自然言語の韓国語／英語も使えます。
2. ページサイズのパラメーターを調整する — 名前はエンドポイントごとに異なります（search／similar では topK、list／packs では limit、random では count）。このスキルのデフォルトは 3 です（上記の「結果数」テーブルを参照）。正確な検索では 3 のままにし、より広範な探索が必要な場合のみ 10 以上（またはアバターを幅広く閲覧する場合は 50～100）に増やしてください。
3. 検索に失敗した場合：
   • ドキュメント検索に失敗した場合 → .d.mlua を直接読みます。
   • リソース検索に失敗した場合 → 類義語や別のカテゴリで再試行します。listResources(...)（CLI：list）を使い、タイプ／カテゴリ別に閲覧します。
   • POST が {"detail":"There was an error parsing the body"} を返す場合 → ラッパーを迂回し、curl -d '{...}' で JSON をインライン送信しています。セクション 2 の説明に従って msw_resource_api.cjs に切り替えるか、UTF-8 の生本文を POST するそのパターンを再現してください。
4. 複合クエリを使用できます — 例：ドキュメントでは AttackComponent CalcCritical、リソースでは red slime jump。
5. 推測しないでください — API 名、RUID、列挙値を推測せず、必ず検索またはリファレンスで確認してください。