Msw Search

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.

Avatar Lookup

Search avatar costume items, browse the full avatar catalog, look up default parts, and inspect item details.

**All examples in this file go through the Node.js wrapper

scripts/msw_resource_api.cjs.** Use it either as a CLI from a

shell or via require(...) inside Node.js — never assemble curl commands

by hand.

---

Searching Costume Items — POST /v3/search/resources

Costume items (hats, coats, shoes, weapons, …) are searched through the general resource-search endpoint with resourceTypeFilter: ["avataritem"]. The wrapper exposes this as searchAvatarItems (CLI: search-avatar) and hard-codes that filter, so you only need to pass the query (and optionally a slot category).

# CLI — narrow to a specific slot with --category
node scripts/msw_resource_api.cjs \
    search-avatar "early dismissal" --topK 3 --category shoes

// Node.js
const { searchAvatarItems } = require('./scripts/msw_resource_api.cjs');

const result = await searchAvatarItems("early dismissal", {
  topK: 3,
  categoryFilter: ["shoes"],
});

Each result has type: "avataritem" and a category matching the avatar slot (cap, coat, pants, shoes, weapon, …). Use the id (RUID) to assign to the corresponding Custom*Equip property — see the slot mapping table in the msw-avatar skill.

**For full request/response details (fields like dname, score, hasEmbedding,

payload.color_hex, categoryFilter slot list, pagination via nextOffset/offset),

see the "Avatar Item Search" section in `references/resource/search.md`.**

---

GET /v3/avatars

List all avatar items (server-cached). Best for browsing tabs without a query; for keyword search use searchAvatarItems.

Usage

# CLI — canonical-only (default; deduped by color/shape variant)
node scripts/msw_resource_api.cjs avatars

# Include all variants
node scripts/msw_resource_api.cjs avatars --no-canonical-only

// Node.js
const { listAvatars } = require('./scripts/msw_resource_api.cjs');

const avatars = await listAvatars({ canonicalOnly: true });

Response

{
  "items": [
    {
      "ruid": "d9e9948624a54255b079df8dba096f47",
      "category": "coat",
      "names": {"ko": ["Yellow Frill Sleeveless"]},
      "dname": "coat-541",
      "group_id": "coat:757587b9bf92",
      "color_hex": "#eeac19",
      "group_size": 2,
      "group_canonical": false,
      "group_members": [...]
    }
  ],
  "nextOffset": null,
  "total": null
}

---

GET /v3/avatars/defaults

Fetch the default avatar body / head RUIDs.

Usage

# CLI
node scripts/msw_resource_api.cjs \
    avatar-defaults

// Node.js
const { getAvatarDefaults } = require('./scripts/msw_resource_api.cjs');

const defaults = await getAvatarDefaults();

Response

{
  "body": "body_ruid_32hex",
  "head": "head_ruid_32hex"
}

body and head are the base avatar parts used with costume item slots.

---

Inspecting an avatar item — use GET /v3/resources/{ruid}

There is no `/v3/avatars/{ruid}` endpoint. Avatar item details

live behind the same GET /v3/resources/{ruid} endpoint that returns

sprites, animationclips, and resource_packs.

Usage

# CLI
node scripts/msw_resource_api.cjs \
    get ITEM_RUID

// Node.js
const { getResource } = require('./scripts/msw_resource_api.cjs');

const item = await getResource("ITEM_RUID");

Response (avataritem branch)

{
  "id": "71ce85c4acf04770949b7a55488974c2",
  "type": "avataritem",
  "category": "cap",
  "names": {"ko": ["Orange Mushroom Beanie"]},
  "dname": "cap-895",
  "payload": {
    "color_hex": "#ed8316",
    "group_size": 2,
    "group_canonical": false,
    "group_members": [...],
    "group_id": "cap:..."
  }
}

Workflows

Costume item search → application

1. searchAvatarItems("...", { topK: N, categoryFilter: [slot] }) → obtain RUID 2. Use the slot mapping table in the msw-avatar skill to assign the RUID to the correct Custom*Equip property 3. Edit ./Global/DefaultPlayer.model or the relevant .map file → refresh

Inspecting avatar item details

1. searchAvatarItems("...") → search for a costume item and get its RUID 2. getResource(ruid) → inspect color_hex / group meta / variants

Listing, Random Recommendations, and Pack Lookups

Browse resources by type/category, get random recommendations, and find which resource packs include a given RUID.

**All examples in this file go through the Node.js wrapper

scripts/msw_resource_api.cjs.** Use it either as a CLI from a

shell or via require(...) inside Node.js — never assemble curl commands

by hand.

GET /v3/resources

Qdrant Scroll over all resources with embeddings. Supports filters and opaque-string cursor pagination.

Usage

# CLI — list 3 monster sprites
node scripts/msw_resource_api.cjs \
    list --resource-type sprite --category mob --limit 3

// Node.js
const { listResources } = require('./scripts/msw_resource_api.cjs');

const result = await listResources({
  resourceTypeFilter: ["sprite"],
  categoryFilter: ["mob"],
  limit: 3,
});
// Next page:
const nextPage = await listResources({
  resourceTypeFilter: ["sprite"],
  categoryFilter: ["mob"],
  limit: 3,
  offset: result.nextOffset,
});

**Earlier wrapper used type / category (singular, string) and

offset=0 (int).** Both are wrong: the server expects array filters

named resourceTypeFilter / categoryFilter, and offset is an

opaque string cursor (null for the first page).

Response

{
  "items": [
    {
      "id": "RUID",
      "type": "sprite",
      "category": "mob",
      "names": {"ko": ["초록버섯"], "en": ["Green Mushroom"]},
      "payload": {
        "width": 64,
        "height": 64,
        "thumbnail": "https://..."
      }
    }
  ],
  "nextOffset": "0008f952-65b8-56bc-9023-98f3eeb28730",
  "total": null
}

nextOffset is the cursor for the next page (pass it back in offset). Reaches null at the end.

---

GET /v3/resources/random

Random resource recommendation — useful for inspiration or when you just need a sample.

Usage

# CLI — 3 random monster sprites
node scripts/msw_resource_api.cjs \
    random --resource-type sprite --category mob --count 3

# 3 random voice clips
node scripts/msw_resource_api.cjs \
    random --resource-type voice --count 3

# Fully random with no filters (always specify count explicitly — default 3)
node scripts/msw_resource_api.cjs \
    random --count 3

// Node.js
const { randomResources } = require('./scripts/msw_resource_api.cjs');

const result = await randomResources({
  resourceTypeFilter: ["sprite"],
  categoryFilter: ["mob"],
  count: 3,
});

Earlier wrapper sent `limit` / `type` / `category` — the server's

parameters are count / resourceTypeFilter / categoryFilter.

Response

Same shape as the listing endpoint (items + nextOffset + total).

---

GET /v3/resources/packs/{ruid}

List resource packs that contain the given RUID. The path parameter is a 32-char-hex RUID, NOT a pack id.

Looking up a pack's own contents? Use getResource(packId)

(i.e. GET /v3/resources/{packId}) instead — that endpoint returns

the pack with each payload.elements[*] already populated.

Usage

# CLI — find packs that include this animationclip RUID
node scripts/msw_resource_api.cjs \
    packs e5fff311269b464984a9b7885a6401e7 --limit 3

// Node.js
const { findPacksContaining } = require('./scripts/msw_resource_api.cjs');

const packs = await findPacksContaining("e5fff311269b464984a9b7885a6401e7", { limit: 3 });

Response

{
  "items": [
    {
      "id": "npc/9072309.img",
      "type": "resource_pack",
      "category": "npc",
      "names": {"ko": ["주황버섯"]},
      "assetGuid": "304aba4bea874f948a7548c0d8e393f5",
      "payload": {
        "elements": [
          {
            "resource_type": "animationclip",
            "ruid": "0a4cee60c89a42bea0d52fd8df00f17c",
            "rel_path": "move"
          },
          {
            "resource_type": "animationclip",
            "ruid": "e5fff311269b464984a9b7885a6401e7",
            "rel_path": "stand"
          }
        ]
      }
    }
  ]
}

Pack contents (use getResource instead)

To fetch a pack's full contents — same elements array but with each element's payload also filled in — call getResource(packId):

const { getResource } = require('./scripts/msw_resource_api.cjs');

const pack = await getResource("npc/1013617.img");
for (const element of pack.payload.elements) {
  // element has resource_type, ruid, rel_path, and payload (width/height/thumbnail/...)
}

A resource pack usually consists of multiple animations (stand, walk, attack, etc.), sounds, and per-frame sprites. The RUID of an individual element can be used directly in fields like SpriteRendererComponent.SpriteRUID.

Resource Details & Tags

Fetch details for a single or multiple resources, and inspect AI-generated multilingual tags.

**All examples in this file go through the Node.js wrapper

scripts/msw_resource_api.cjs.** Use it either as a CLI from a

shell or via require(...) inside Node.js — never assemble curl commands

by hand.

GET /v3/resources/{ruid}

Fetch detail for a single resource.

Usage

# CLI
node scripts/msw_resource_api.cjs \
    get 0017da7385e04bc4b2ddbe5949b4b462

// Node.js
const { getResource } = require('./scripts/msw_resource_api.cjs');

const detail = await getResource("0017da7385e04bc4b2ddbe5949b4b462");

Response

{
  "id": "0017da7385e04bc4b2ddbe5949b4b462",
  "type": "sprite",
  "category": "mob",
  "names": {
    "ko": ["초록버섯"],
    "en": ["Green Mushroom"]
  },
  "assetGuid": "304aba4bea874f948a7548c0d8e393f5",
  "payload": {
    "width": 64,
    "height": 64,
    "pivot": {"x": 32, "y": 50},
    "thumbnail": "https://...",
    "frames": [
      {"filename": "frame0.png", "delay": 100}
    ],
    "elements": [
      {
        "resource_type": "animationclip",
        "rel_path": "mob/stand",
        "ruid": "element_ruid"
      }
    ]
  }
}

Key payload Fields

• frames exists only on animationclip
• elements exists only on resource_pack
• pivot exists on sprite

---

POST /v3/resources/batch

Fetch multiple RUIDs in a single request.

Usage

# CLI — pass RUIDs as space-separated positional arguments
node scripts/msw_resource_api.cjs \
    batch 0017da7385e04bc4b2ddbe5949b4b462 abc123def456789012345678abcdef01

// Node.js
const { getResourcesBatch } = require('./scripts/msw_resource_api.cjs');

const resources = await getResourcesBatch([
  "0017da7385e04bc4b2ddbe5949b4b462",
  "abc123def456789012345678abcdef01",
]);

Response

An array of resource objects. Each element has the same structure as the single-resource response.

---

GET /v3/resources/tags/{ruid}

Fetch AI-generated multilingual tags for a resource — including description, keywords, and per-language tags.

Usage

# CLI
node scripts/msw_resource_api.cjs \
    tags 0017da7385e04bc4b2ddbe5949b4b462

// Node.js
const { getResourceTags } = require('./scripts/msw_resource_api.cjs');

const tags = await getResourceTags("0017da7385e04bc4b2ddbe5949b4b462");

Response

{
  "tags": {
    "ko": ["초록", "버섯", "몬스터", "슬라임"],
    "en": ["green", "mushroom", "monster", "slime"],
    "ja": ["緑", "キノコ", "モンスター"],
    "zh": ["绿色", "蘑菇", "怪物"],
    "description": "A green mushroom monster from MapleStory",
    "keywords": ["green_mushroom", "mob", "monster"]
  }
}

Tags are generated automatically by AI and describe the resource's visual traits and intended use. They are useful for similar-resource search and for filtering.

Semantic Search & Similar Resources

Search MSW resources by natural language, and find resources similar to a given one.

**All examples in this file go through the Node.js wrapper

scripts/msw_resource_api.cjs.** Use it either as a CLI from a

shell or via require(...) inside Node.js — never assemble curl commands

by hand. The wrapper sends UTF-8 JSON bodies directly, so non-ASCII queries

(Korean / Japanese / Chinese / emoji) are safe and the

{"detail":"There was an error parsing the body"} failure mode is

impossible to trigger.

POST /v3/search/resources

Natural-language semantic search. Supports queries in Korean, English, Japanese, and Chinese.

Usage

# CLI — defaults: topK=3, --resource-type / --category optional
node scripts/msw_resource_api.cjs \
    search "orange mushroom" --resource-type resource_pack --category npc --topK 3

// Node.js — require and call
const { searchResources } = require('./scripts/msw_resource_api.cjs');

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

Use require(...) with a relative path (e.g.

require('./scripts/msw_resource_api.cjs')) when calling from a sibling file —

the wrapper is a single-file CommonJS drop-in with zero dependencies.

**The legacy field names types / categories / limit are silently

ignored by the server.** Always use the canonical names above —

the wrapper takes care of this for you.

Avatar-item search uses the same endpoint with

resourceTypeFilter=["avataritem"] already filled in. Use the

searchAvatarItems wrapper (CLI: search-avatar) — see "Avatar

Item Search" below.

Response

{
  "results": [
    {
      "id": "0017da7385e04bc4b2ddbe5949b4b462",
      "type": "resource_pack",
      "category": "mob",
      "names": {
        "ko": ["초록버섯"],
        "en": ["Green Mushroom"]
      },
      "dname": "Green Mushroom",
      "score": 0.9234,
      "assetGuid": "304aba4bea874f948a7548c0d8e393f5",
      "payload": {
        "width": 64,
        "height": 64,
        "thumbnail": "https://...",
        "elements": [
          {
            "resource_type": "animationclip",
            "rel_path": "mob/9833419.img/move",
            "ruid": "abc123..."
          }
        ]
      }
    }
  ],
  "nextOffset": 5
}

Key Response Fields

Choosing resourceTypeFilter

• Default: resource_pack — a finished asset bundling sprites + animations + sounds; suitable for most searches
• Sound / audio: bgm (background music) / voice (NPC voice) / effect (sound effect — not visual)
• Individual sprite: sprite
• Individual animation: animationclip
• Visual effect / particle / hit FX: sprite or animationclip + categoryFilter: ["skill","mob","etc"] — there is no visual effect resource_type or category
• Avatar costume item: avataritem (or just call searchAvatarItems)

Using categoryFilter

Search Tips

• If you miss on the first try, retry with synonyms / English / Korean:
• "tree" → "forest" → "forest background" → "plant"
• "running monster" → "moving monster" → "moving enemy"
• You can also pass a RUID directly as query.

---

Avatar Item Search (resourceTypeFilter: ["avataritem"])

The same POST /v3/search/resources endpoint also covers avatar costume items (hats, coats, shoes, weapons, etc.). This is the only supported way to obtain avatar item RUIDs by natural-language search — the legacy full-list endpoint is no longer used.

The wrapper hard-codes resourceTypeFilter=["avataritem"]. You can narrow the search to a specific avatar slot by passing categoryFilter: ["cap", ...] (CLI: --category cap).

Usage

# CLI
node scripts/msw_resource_api.cjs \
    search-avatar "early dismissal" --topK 3 --category shoes

// Node.js
const { searchAvatarItems } = require('./scripts/msw_resource_api.cjs');

const result = await searchAvatarItems("early dismissal", {
  topK: 3,
  categoryFilter: ["shoes"],
});

The wrapper hard-codes resourceTypeFilter=["avataritem"], so you do not

need to pass it explicitly.

Response

{
  "query": "early dismissal",
  "results": [
    {
      "id": "ac02d9eb84dc4c4197dfce6721c6543c",
      "type": "avataritem",
      "category": "shoes",
      "names": { "ko": ["이른 하교"] },
      "dname": "shoes-1141",
      "assetGuid": null,
      "score": 0.78686994,
      "hasEmbedding": true,
      "payload": {
        "color_hex": "#981125",
        "group_size": null,
        "group_canonical": null,
        "group_members": null,
        "group_id": null
      }
    }
  ],
  "nextOffset": 2,
  "exactMatch": false
}

Avatar-Specific Response Fields

Tips

• The default topK is 3 (this skill's convention). Increase to 50–100 only when explicitly browsing widely.
• category in avatar item results aligns with avatar slots (cap, coat, pants, shoes, weapon, …) — use the slot mapping table in the msw-avatar skill to assign to the correct Custom*Equip property.
• payload.color_hex lets you filter results client-side, e.g. "red shoes" → search "shoes", then keep entries whose color_hex is reddish.

---

GET /v3/search/resources/similar/{id}

Find resources that are visually or semantically similar to a given resource.

Usage

# CLI
node scripts/msw_resource_api.cjs \
    similar 0017da7385e04bc4b2ddbe5949b4b462 --topK 3 --resource-type animationclip

// Node.js
const { findSimilarResources } = require('./scripts/msw_resource_api.cjs');

const result = await findSimilarResources("0017da7385e04bc4b2ddbe5949b4b462", {
  topK: 3,
  resourceTypeFilter: ["animationclip"],
});

Earlier wrapper sent limit; the server's parameter is `topK`.

Response

An array with the same structure as search results. score represents similarity to the source resource.