msw-search

name: msw-search description: "MSW search integration — (1) vector search for API docs and implementation guides via the msw-mcp MCP server (mlua_api_retriever / mlua_document_retriever), (2) REST API search for resources (sprite / animation / sound / resource pack / avatar). Use for 'find details, examples, or related APIs not in .d.mlua', 'need a SpriteRUID', 'monster sprite', 'background image', 'find a sound', 'avatar item lookup', etc. Keywords: document search, API details, examples, guide, retriever, resource, sprite, animation, sound, RUID, resource pack, avatar."

MSW Search

MSW has two distinct search targets:

1. API docs & implementation guides — Vector search for descriptions, code examples, and related APIs missing from .d.mlua.
2. Resources — REST API for sprites, animations, sounds, resource packs, and avatars. The only path for obtaining RUIDs.

Routing Table

★ Resource search default — always resource_pack first

Unless the user explicitly asks for an individual sprite / animationclip / sound / avatar item (or names a non-pack RUID directly), pass resourceTypeFilter: ["resource_pack"] to searchResources. A pack bundles every sprite + animation + sound for one asset, so picking a stray sprite or animationclip first usually leaves the entity with a single frame, no animation set, or the wrong asset family.

Search the pack → drill into payload.elements → assign individual RUIDs. Switch types only on explicit intent: "BGM file", "individual sprite only", "avatar item", "animationclip similar to this RUID", etc.

Section 1 — Document Search (APIs & Guides)

Vector search via the msw-mcp MCP server. Supplies the detailed descriptions, code examples, related APIs, and implementation guides missing from .d.mlua.

Decision Flow

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 Research Order

Priority 1 — .d.mlua (always first)

If you know the API name, always read .d.mlua first. Signatures, types, properties, event parameters, and enum values can be confirmed here accurately.

Path: Environment/NativeScripts/{Component,Service,Event,Enum,Logic,Misc}/Name.d.mlua

Priority 2 — Vector search (when .d.mlua is not enough)

.d.mlua contains only signatures and lacks detailed descriptions and examples. Use vector search when you need any of the following.

MCP Tools (msw-mcp)

On failure: If a msw-mcp tool call errors out, surface the failure to the user and fall back to .d.mlua. Do not guess — state what you couldn't verify.

Default result count: request 3 results unless wider exploration is explicitly required.

.d.mlua vs Search — Information Comparison

.d.mlua is a type stub (~29 lines); Search returns the full document (254+ lines).

Maker Editor Syntax → .mlua Conversion Rules

Code examples in search results use Maker Editor syntax. They must be converted before being used in a local .mlua file.

number (64-bit double) and float (32-bit single) are assignable to each other but remain distinct types. Follow the .d.mlua declaration.

⚠ Override ExecSpace caveat — LEA-3014 SignatureMismatch

The Maker Editor often hides the parent's exec space and lets you toggle [server only] freely on an override block. In .mlua, however, the override's @ExecSpace must be byte-identical to the parent declared in .d.mlua. If the parent has no @ExecSpace (engine default = ExecSpace=All), the override must also omit @ExecSpace entirely.

Concretely, the AttackComponent / HitComponent damage hooks (CalcDamage, CalcCritical, GetCriticalDamageRate, GetDisplayHitCount, IsAttackTarget, IsHitTarget, OnAttack) are all ExecSpace=All upstream. Adding @ExecSpace("ServerOnly") produces:

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

Always look up the parent in .d.mlua first and copy its annotation block verbatim. Detail: msw-scripting/SKILL.md §9 "Method override → LEA-3014".

Conversion example — AttackComponent from search results:

-- 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

Section 2 — Resource Search (Sprite / Animation / Sound / Resource Pack / Avatar)

REST API for searching and browsing MSW resources. Never guess or fabricate a RUID — always obtain one through this API.

Default search type = resource_pack — see the pack-first rule under the Routing Table above.

Access — always go through msw_resource_api.cjs

All resource-API calls in this skill are made through the Node.js wrapper

scripts/msw_resource_api.cjs

Do not assemble curl commands by hand. The wrapper:

• Sends UTF-8 JSON bodies directly, so non-ASCII queries (Korean / Japanese / Chinese / emoji) avoid the {"detail":"There was an error parsing the body"} failure mode that hits inline curl -d '...'.
• URL-encodes slash-containing path parameters (e.g. pack IDs like npc/1013617.img).
• Zero dependencies (Node 18+ built-in fetch / AbortController).
• Uses the exact OpenAPI field names (topK, resourceTypeFilter, categoryFilter, count, …). Legacy names like limit / types / categories are silently ignored by the server.

Two ways to use it:

# 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,
});

Wrapper function ↔ endpoint map

No /v3/avatars/{ruid} endpoint exists. To inspect an avataritem (color_hex, group members, …), call getResource(ruid) — the /v3/resources/{ruid} endpoint returns avataritem detail just like any other resource.

Base URL & transport (informational)

The wrapper handles all of this — you do not need to set it manually.

• Base URL: https://maplestoryworlds-resourcesearch-new.nexon.com/api
• No auth (public), /v3/ prefix, POST bodies are application/json; charset=utf-8
• Default timeout: 15s (override via the wrapper's _request(method, path, { timeout }))

Result count — this skill's default is 3

Unless explicitly told otherwise, always send 3 for the result-count parameter on every search call. The wrapper defaults to 3 as well, and parameter names follow the OpenAPI spec exactly — note that limit / count / topK differ per endpoint.

The server-side default is 20 or 50, so always pass these parameters explicitly. Increase to 10+ (or 50–100 for avatar broad-browse) only when wider exploration is explicitly required.

offset parameter caveat — for GET /v3/resources and GET /v3/resources/packs/{ruid}, offset is not an integer but the opaque string cursor nextOffset returned by the previous response. Do not send it on the first page (sending integer 0 is interpreted as a cursor and returns empty results).

POST body rule — let msw_resource_api.cjs handle it

If you must POST without the wrapper (no HTTP client in your language), reproduce its behaviour:

1. Serialize the body as UTF-8 JSON bytes (not a re-encoded shell string).
2. Send Content-Type: application/json; charset=utf-8.
3. POST raw bytes (e.g. curl's --data-binary "@file" reading a UTF-8 temp file).

Otherwise, just call the wrapper.

Resource Types

type values (the type field on server responses, and the values you put into the resourceTypeFilter array when searching):

All search and listing endpoints use the same type-filter field name: resourceTypeFilter (an array). Other names like types are silently ignored by the server. The wrapper's resource_type_filter argument (or CLI --resource-type) maps to this field.

⚠ SpriteRendererComponent.SpriteRUID accepts both sprite and animationclip, but renders them differently:

• animationclip → all frame layers play (shadow + body + foreground)
• sprite → that single Sprite renders only

Symptom of mistake: feeding an animationclip RUID where you intended a sprite (or vice-versa) leaves only the shadow layer visible — the body silently vanishes. Always check payload.type of the response before assigning to SpriteRUID. Use sprite for the static idle/default frame; use animationclip only for fields like StateAnimationComponent.ActionSheet values.

skeleton and avataritem RUIDs fail silently (no error, nothing renders) when assigned to SpriteRUID / ImageRUID without the thumbnail:// prefix. Conversely, CostumeManagerComponent.Custom*Equip / SkeletonRendererComponent.SkeletonRUID / StateAnimationComponent.ActionSheet do not accept the thumbnail:// prefix — pass a plain RUID there. If the search query targeted an icon / thumbnail image and returned a sprite RUID, that RUID is already renderable directly — adding thumbnail:// is redundant. Full assignment rules — accepted types, slot-by-slot prefix matrix, RUID-vs-prefix usage — live in msw-sprite-ruid/SKILL.md.

Categories

category values that actually appear on responses. Use these with categoryFilter.

General resources (sprite / animationclip / resource_pack / bgm / voice / effect)

Avatar (avataritem only)

map, effect, ui are not valid category values — they return zero results.

• Looking for maps / backgrounds → category: "background" or "object".
• Looking for visual effects → search sprite / animationclip with category: "skill" (or mob/etc); effect is the audio resource_type, not a category.
• There is no ui resource family in this index — UI sprites usually live as sprite + category: "etc".

RUID

A 32-character hex string that uniquely identifies every resource. Example: "0017da7385e04bc4b2ddbe5949b4b462"

• The id field in search results is the RUID
• assetGuid is a separate Unity asset GUID (used in spawn_preset)
• Never guess or fabricate a RUID — always obtain it from an API response

Common Response Fields

{
  "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": []
  }
}

Pagination — same name, two flavors

nextOffset appears in every list-style response but means different things depending on the endpoint. Round-tripping a value into the wrong endpoint silently misbehaves.

Rules:

1. Never feed a list cursor into a search call (or vice versa) — the server ignores the wrong-shape value and returns the first page.
2. On the first page, omit offset entirely. Sending integer 0 to list / packs is interpreted as a cursor and yields zero items (silent failure).
3. Stop paginating when the response returns nextOffset: null (list / packs) or returns fewer items than topK (search / similar).

Endpoint Summary

Single avataritem detail uses /v3/resources/{ruid} (no /v3/avatars/{ruid} endpoint exists).

Resource Routing Guide

★ When in doubt, search resource_pack first. Only the rows marked with an explicit non-pack intent below should bypass the pack-first default.

Typical Workflow (pack-first)

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`)

Don't call findPacksContaining(packId) to "open" a pack — that endpoint takes a 32-hex RUID and returns the packs that include that RUID, not the contents of a pack. Use getResource(packId) for pack contents.

For detailed Request/Response of each endpoint, refer to the files under references/resource/.

Sprite Orientation — Most Resources Face Left

Most MSW sprite / animationclip / resource_pack assets — especially mob, npc, and player-character — are authored facing left, so a freshly spawned SpriteRendererComponent renders left unless you flip it.

-- 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

Sanity check — the left-facing convention is not contractual. Open payload.thumbnail from GET /v3/resources/{ruid} to confirm.

Do not use TransformComponent.Scale.x as a general renderer flip — for players / effects / non-monster renderers, use SpriteRendererComponent.FlipX. Monster exception: monster models should invert TransformComponent.Scale.x so the sprite and collider stay aligned. Related: msw-combat-system/SKILL.md "Direction check ★", msw-general/references/monster.md.

Shared Tips

1. Keyword choice — Use the exact name if you know it; natural-language Korean/English also works.
2. Adjust the page-size parameter — the name differs per endpoint (topK for search/similar, limit for list/packs, count for random). This skill's default is 3 (see the "Result count" table above). Keep it at 3 for precise lookups; increase to 10+ (or 50–100 for avatar broad-browse) only when wider exploration is required.
3. When search fails:
   • Document search fails → read .d.mlua directly.
   • Resource search fails → retry with synonyms or a different category; browse with listResources(...) (CLI: list) by type/category.
   • POST returns {"detail":"There was an error parsing the body"} → you bypassed the wrapper and sent JSON inline via curl -d '{...}'. Switch to msw_resource_api.cjs (or replicate its UTF-8 raw-body POST pattern) as described in Section 2.
4. Composite queries are allowed — e.g. AttackComponent CalcCritical for docs, red slime jump for resources.
5. No guessing — Never guess API names, RUIDs, or enum values; always confirm via search or references.