msw-search

MSW 搜索

MSW 有 两个不同的搜索目标：

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），否则将 resourceTypeFilter: ["resource_pack"] 传给 searchResources。一个资源包包含某个资产的所有精灵 + 动画 + 声音，因此先随意挑选一个 sprite 或 animationclip，通常会导致实体只有单帧、没有动画集，或使用了错误的资产系列。

先搜索资源包 → 深入查看 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 位 double）和 float（32 位 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 节 — 资源搜索（精灵 / 动画 / 音效 / 资源包 / Avatar）

用于搜索和浏览 MSW 资源的 REST API。 切勿猜测或伪造 RUID — 务必通过此 API 获取。

默认搜索类型 = resource_pack — 参见上方路由表中的资源包优先规则。

访问方式 — 始终通过 msw_resource_api.cjs

此技能中的所有资源 API 调用都通过 Node.js 封装器进行

scripts/msw_resource_api.cjs

**请勿手动拼接 curl 命令。**此封装器：

• 直接发送 UTF-8 JSON 请求体，因此非 ASCII 查询（韩文 / 日文 / 中文 / emoji）可避免内联 curl -d '...' 遇到的 {"detail":"There was an error parsing the body"} 失败情况。
• 对包含斜杠的路径参数进行 URL 编码（例如 npc/1013617.img 这类资源包 ID）。
• 零依赖（内置于 Node 18+ 的 fetch / AbortController）。
• 使用准确的 OpenAPI 字段名称（topK、resourceTypeFilter、categoryFilter、count 等）。limit / types / categories 等旧名称会被服务器静默忽略。

有两种使用方式：

# 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（avatar 模式）
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（资源 + avatar）	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 以上（或在广泛浏览 avatar 时增至 50–100）。

offset 参数注意事项——对于 GET /v3/resources 和 GET /v3/resources/packs/{ruid}， offset 不是整数，而是前一次响应返回的不透明字符串游标 nextOffset。 第一页不要发送该参数（发送整数 0 会被解释为游标，并返回空结果）。

POST 请求体规则——交由 msw_resource_api.cjs 处理

如果必须在不使用包装器的情况下发送 POST 请求（你的语言没有 HTTP 客户端），请复现其行为：

1. 将请求体序列化为 UTF-8 JSON 字节（不要重新编码 shell 字符串）。
2. 发送 Content-Type: application/json; charset=utf-8。
3. 发送原始字节（例如使用 curl 的 --data-binary "@file" 读取 UTF-8 临时文件）。

否则，直接调用包装器。

资源类型

type 的取值（服务器响应中的 type 字段，以及搜索时填入 resourceTypeFilter 数组的值）：

type	描述
sprite	静态图像（PNG）
animationclip	基于帧的动画
resource_pack	已完成的资源包，包含精灵图、动画和音效
bgm	背景音乐（音频）
voice	语音片段——NPC 对话等（音频）
effect	音效（音频）。 不是视觉特效。若要查找视觉粒子、命中或技能特效，请搜索 sprite 或 animationclip（分类为 skill / mob / etc）。
avataritem	角色服装物品（帽子、外套、裤子、鞋子、武器等）——使用相同的 POST /v3/search/resources 端点，并设置 resourceTypeFilter: ["avataritem"]。请参阅 references/resource/search.md（“Avatar Item Search”）和 references/resource/avatar.md。

所有搜索和列表端点都使用相同的类型筛选字段名：resourceTypeFilter （一个数组）。服务器会静默忽略 types 等其他名称。 封装器的 resource_type_filter 参数（或 CLI 的 --resource-type）会映射到此字段。

⚠ SpriteRendererComponent.SpriteRUID 接受 sprite 和 animationclip，但渲染方式不同：

• animationclip → 播放所有帧图层（阴影 + 身体 + 前景）
• sprite → 仅渲染该单张 Sprite

错误表现：将 animationclip 的 RUID 用在本应使用 sprite 的地方（反之亦然），会导致只显示阴影图层——身体会静默消失。赋值给 SpriteRUID 前，务必检查响应的 payload.type。静态待机/默认帧请使用 sprite；仅在 StateAnimationComponent.ActionSheet 值等字段中使用 animationclip。

将 skeleton 和 avataritem 的 RUID 赋值给 SpriteRUID / ImageRUID 时，若未添加 thumbnail:// 前缀，会静默失败（不报错，也不渲染任何内容）。 反过来，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 不是有效的分类值——使用它们会返回零条结果。

• 查找地图 / 背景 → 使用 category: "background" 或 "object"。
• 查找视觉特效 → 搜索 sprite / animationclip，分类设为 skill（或 mob / etc）；effect 是音频资源类型，而不是分类。
• 此索引中没有 ui 资源系列——UI 精灵图通常属于 sprite + category: "etc"。

RUID

一个 32 字符的十六进制字符串，用于唯一标识每个资源。例如："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": []
  }
}

分页——同一名称，两种形式

nextOffset 会出现在所有列表型响应中，但根据端点不同，含义也不同。将某个值传入错误的端点会导致行为异常，而且不会提示错误。

端点	nextOffset 类型	含义	分页方式
POST /v3/search/resources（搜索）	整数	项目偏移量（从 0 开始）	将其作为 offset（数字）传回
GET /v3/search/resources/similar/{id}（相似项）	整数	项目偏移量	同上
GET /v3/resources（列表）	不透明的 UUID 字符串	Qdrant Scroll 游标	将字符串作为 offset 传回。流结束 = null
GET /v3/resources/packs/{ruid}（资源包）	不透明的 UUID 字符串	同一游标	同上
GET /v3/resources/random	不适用	不支持分页	—

规则：

1. 切勿将 list 游标传给 search 调用（反之亦然）——服务端会忽略格式不匹配的值，并返回第一页。
2. 在第一页中，完全省略 offset。向 list / packs 传入整数 0 会被解释为游标，并返回零个项目（静默失败）。
3. 当响应返回 nextOffset: null（list / packs），或返回的项目数少于 topK（search / similar）时，停止分页。

端点摘要

方法	端点	用途
POST	/v3/search/resources	自然语言语义搜索（包括通过 resourceTypeFilter: ["avataritem"] 搜索 avatar 项目）
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 Scroll，不透明字符串 offset 游标）
GET	/v3/resources/random	随机资源推荐
GET	/v3/resources/packs/{ruid}	列出包含指定 RUID 的资源包——路径参数是 32 字符的十六进制 RUID，而不是资源包 id
GET	/v3/avatars	列出所有 avatar 项目（已缓存）
GET	/v3/avatars/defaults	默认 avatar 身体 / 头部 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 资源类型 = 音效（音频）	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 的详情”（任意类型，包括 avataritem 和 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 位十六进制 RUID，并返回包含该 RUID 的资源包，而非资源包的内容。要获取资源包内容，请使用 getResource(packId)。

各端点的详细请求 / 响应信息，请参阅 references/resource/ 下的文件。

---

Sprite 朝向 — 大多数资源面朝左

大多数 MSW sprite / animationclip / resource_pack 资源——尤其是 mob、npc 和玩家角色——创建时都面朝左，因此新生成的 SpriteRendererComponent 默认会朝左渲染，除非你将其翻转。

情况	操作
生成一个应面朝右的实体	在 SpriteRendererComponent 上设置 FlipX = true（默认值为 false，即按创建时的朝向面朝左）
使用 MovementComponent:MoveToDirection 自定义 AI / 追逐行为	方向改变时更新 FlipX：sprite.FlipX = velocity.x > 0（朝右 ⇒ 翻转）
怪物模型 / 怪物碰撞体对齐	反转 TransformComponent.Scale.x，而不是 FlipX，以保持精灵与碰撞体对齐；参见 msw-general/references/monster.md
原生 AIChaseComponent / AIWanderComponent	引擎会根据移动自动翻转——无需处理
俯视角（RectTile）移动	按轴决定：通常在 dx > 0 时翻转；带有上下帧的精灵则需要设置 StateAnimationComponent action
_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 "方向检查 ★"、msw-general/references/monster.md。

---

通用提示

1. 关键词选择 — 如果知道确切名称，请使用该名称；自然语言韩语 / 英语也可以。
2. 调整页面大小参数 — 不同端点的参数名称不同（搜索 / 相似项使用 topK，列表 / 资源包使用 limit，随机项使用 count）。此技能的默认值为 3（参见上方的“结果数量”表）。精准查询时保持为 3；只有需要更广泛探索时才增加到 10+（头像广泛浏览可设为 50–100）。
3. 搜索失败时：
   • 文档搜索失败 → 直接读取 .d.mlua。
   • 资源搜索失败 → 使用同义词或其他类别重试；按类型 / 类别使用 listResources(...) 浏览（CLI：list）。
   • POST 返回 {"detail":"There was an error parsing the body"} → 你绕过了封装器，通过 curl -d '{...}' 内联发送了 JSON。请改用 msw_resource_api.cjs（或按第 2 节所述，复现其 UTF-8 原始请求体 POST 模式）。
4. 允许组合查询 — 例如，文档可查询 AttackComponent CalcCritical，资源可查询 red slime jump。
5. 不要猜测 — 切勿猜测 API 名称、RUID 或枚举值；务必通过搜索或参考资料确认。