msw-search

SKILL.md

MSW Search

MSW has two distinct search targets:

API docs & implementation guides — Vector search for descriptions, code examples, and related APIs missing from .d.mlua.

Resources — REST API for sprites, animations, sounds, resource packs, and avatars. The only path for obtaining RUIDs.

Routing Table

Request type
Go to section

"How do I implement this?", "Show me an example", "What related APIs exist?"
Document search

".d.mlua only has the signature; the description is insufficient"
Document search

"I don't know the API name (semantic search)"
Document search

"Implementation guide / best practice / pattern"
Document search

"I need a SpriteRUID", "Find a sprite for monster / NPC / background"
Resource search → start with resource_pack

"Find an animation / sound / resource pack"
Resource search → start with resource_pack

"Details for this RUID", "Similar resources"
Resource search

"Avatar item / default avatar lookup"
Resource search

"Upload / list / update / delete my own assets"
Call msw-mcp asset_* tools directly

"Set sprite pivot", "set 9-slice border", "slice boundary for UI RUID", "asset properties"
Call msw-mcp asset_update_resource_storage_info directly (properties: [{ key, value }] — pivot_x/y, border_left/right/top/bottom, filter_mode, wrap_mode)

★ 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

Situation
Example

Confirm method signature
"Does TransformComponent have SetPosition?"

Property type / existence
"What is the type of SpriteRendererComponent.RUID?"

Event parameter structure
"What are the AttackEvent constructor parameters?"

List of enum values
"What are the BodyMoveType values?"

Method existence
"What methods does SpawnService have?"

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.

Situation
MCP tool
Example query

Need a code example
mlua_api_retriever
AIComponent example, BehaviorTree usage

Parameter details
mlua_api_retriever
BadgeService GetBadgeInfosAndWait parameters

Related API cross-references
mlua_api_retriever
AttackComponent related, HitComponent

ScriptOverridable check
mlua_api_retriever
AttackComponent CalcCritical override

Don't know the API name
both retrievers
damage calculation, inventory save

"How do I …?" implementation guide
mlua_document_retriever
how to make inventory system

Pattern / best practice
mlua_document_retriever
collision detection best practice

MCP Tools (msw-mcp)

Tool
Description

mlua_api_retriever
API details for Service / Component / Misc etc. (signatures, parameters, examples). Pass an API/class/function/component name.

mlua_document_retriever
Authoring manuals, guidelines, MLua usage, and other document-style material. Pass a natural-language sentence describing what to implement.

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

Information
.d.mlua
Search

Method signature / types
O
O

Property declarations
O
O

Detailed method description (DetailDesc)
X
O

Code examples (AdditionalPageContent)
X
O

Per-parameter descriptions
X
O

Related APIs (SeeAlsoAPIs)
X
O

Related guides (SeeAlsoGuides)
X
O

ScriptOverridable flag
X
O

SyncDirection
Partial
O

Localized descriptions (Ko/Ja/Es/Zh)
X
O

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.

Item
Maker Editor
.mlua file
Note

Override declaration
override integer CalcDamage(...)
method integer CalcDamage(...)
override → method

Block
{ ... }
... end
Braces → end

Exec space (own method)
[server only]
@ExecSpace("ServerOnly")
Self-defined methods: annotate explicitly

Exec space (override)
[server only] shown / omitted in editor
Match the parent's @ExecSpace exactly — see warning below
LEA-3014 if mismatched

Property
Property: int32 Score = 0
@Sync property int32 Score = 0
Add @Sync if synced

Type int
int
integer
C# int → mlua integer

Type number
number
number
Same (double)

Type float
float
float
Same (single)

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

Wrapper function
CLI subcommand
Endpoint

searchResources
search
POST /v3/search/resources

searchAvatarItems
search-avatar
POST /v3/search/resources (avatar mode)

findSimilarResources
similar
GET /v3/search/resources/similar/{ruid}

getResource
get
GET /v3/resources/{ruid} (works for 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, opaque-string offset cursor)

randomResources
random
GET /v3/resources/random

findPacksContaining
packs
GET /v3/resources/packs/{ruid} (lists packs containing a RUID — pack id is NOT accepted here)

listAvatars
avatars
GET /v3/avatars

getAvatarDefaults
avatar-defaults
GET /v3/avatars/defaults

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.

Endpoint
Server parameter
Wrapper default

POST /v3/search/resources (resources + avatar)
topK
3

GET /v3/search/resources/similar/{ruid}
topK
3

GET /v3/resources (browsing)
limit
3

GET /v3/resources/random
count
3

GET /v3/resources/packs/{ruid} (packs containing a RUID)
limit
3

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:

Serialize the body as UTF-8 JSON bytes (not a re-encoded shell string).

Send Content-Type: application/json; charset=utf-8.

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

type
Description

sprite
Static image (PNG)

animationclip
Frame-based animation

resource_pack
Finished asset bundling sprites + animations + sounds

bgm
Background music (audio)

voice
Voice clip — NPC dialogue, etc. (audio)

effect
Sound effect (audio). Not a visual effect. For visual particles / hit / skill FX, search sprite or animationclip (categories skill / mob / etc).

avataritem
Avatar costume item (cap, coat, pants, shoes, weapon, …) — same POST /v3/search/resources endpoint with resourceTypeFilter: ["avataritem"]. See references/resource/search.md ("Avatar Item Search") and references/resource/avatar.md.

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)

category
Description

mob
Monster

npc
NPC

item
Item

skill
Skill effect / skill resources

object
Map object (tree, rock, decoration)

background
Background / map tile / BGM

foothold
Walkable platform

rope
Rope

ladder
Ladder

etc
Uncategorized

Avatar (avataritem only)

category
Slot

cap, hair, face, faceaccessory, eyeaccessory, earaccessory
Head / face

coat, longcoat, pants, shoes, glove, cape
Body

weapon, twohandweapon, subweapon, shield
Weapon

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.

Endpoint
nextOffset type
Meaning
How to paginate

POST /v3/search/resources (search)
integer
Item offset (0-based)
Pass it back as offset (number)

GET /v3/search/resources/similar/{id} (similar)
integer
Item offset
Same

GET /v3/resources (list)
opaque UUID string
Qdrant Scroll cursor
Pass the string back as offset. End-of-stream = null

GET /v3/resources/packs/{ruid} (packs)
opaque UUID string
Same cursor
Same

GET /v3/resources/random
n/a
No pagination
—

Rules:

Never feed a list cursor into a search call (or vice versa) — the server ignores the wrong-shape value and returns the first page.

On the first page, omit offset entirely. Sending integer 0 to list / packs is interpreted as a cursor and yields zero items (silent failure).

Stop paginating when the response returns nextOffset: null (list / packs) or returns fewer items than topK (search / similar).

Endpoint Summary

Method
Endpoint
Purpose

POST
/v3/search/resources
Natural-language semantic search (incl. avatar items via resourceTypeFilter: ["avataritem"])

GET
/v3/search/resources/similar/{ruid}
Find similar resources

GET
/v3/resources/{ruid}
Single resource details (sprite / animationclip / resource_pack with populated elements / avataritem)

POST
/v3/resources/batch
Batch fetch multiple resources

GET
/v3/resources/tags/{ruid}
AI-generated multilingual tags

GET
/v3/resources
List resources (Qdrant Scroll, opaque-string offset cursor)

GET
/v3/resources/random
Random resource recommendation

GET
/v3/resources/packs/{ruid}
List resource packs containing the given RUID — the path parameter is a 32-char-hex RUID, not a pack id

GET
/v3/avatars
List all avatar items (cached)

GET
/v3/avatars/defaults
Default avatar body / head RUIDs

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.

Situation
Wrapper call (CLI subcommand)
Reference file

"Find a slime / orange mushroom / monster / NPC / item / background / map asset" (default — no type specified)
searchResources(query, { resourceTypeFilter: ["resource_pack"], ... }) (search ... --resource-type resource_pack)
references/resource/search.md

"Find an individual sprite / single image" (user explicitly asked for a sprite)
searchResources(query, { resourceTypeFilter: ["sprite"], ... })
references/resource/search.md

"Find an individual animationclip" (user explicitly asked for an animation)
searchResources(query, { resourceTypeFilter: ["animationclip"], ... })
references/resource/search.md

"Find a visual effect / particle / hit FX"
searchResources(query, { resourceTypeFilter: ["animationclip","sprite"], categoryFilter: ["skill","mob","etc"] }) — note: effect here would mean audio, not visual
references/resource/search.md

"Find a sound / BGM / voice / sound-effect" (audio)
searchResources(query, { resourceTypeFilter: ["bgm"|"voice"|"effect"], ... }) — effect resource_type = sound-effect (audio)
references/resource/search.md

"Find a background / map tile / scenery"
searchResources(query, { resourceTypeFilter: ["sprite","animationclip"], categoryFilter: ["background","object"] }) — there is no map category in the index
references/resource/search.md

"Find a costume / hat / shoes / weapon (avatar item)"
searchAvatarItems(...) (search-avatar)
references/resource/search.md (Avatar Item Search section) + references/resource/avatar.md

"Any more monsters like this one?"
findSimilarResources(ruid, ...) (similar)
references/resource/search.md

"Details for RUID abc123" (any type incl. avataritem and resource_pack)
getResource(ruid) (get)
references/resource/detail.md

"Show me a list of monster sprites"
listResources(...) (list)
references/resource/browse.md

"Which resource packs include this RUID?"
findPacksContaining(ruid, ...) (packs)
references/resource/browse.md

"Browse all avatar items"
listAvatars(...) (avatars)
references/resource/avatar.md

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.

Situation
What to do

Spawn an entity that should face right
Set FlipX = true on SpriteRendererComponent (default is false = left-facing as authored)

Custom AI / chase using MovementComponent:MoveToDirection
Update FlipX on direction change: sprite.FlipX = velocity.x > 0 (right ⇒ flip)

Monster model / monster collider alignment
Invert TransformComponent.Scale.x instead of FlipX so the sprite and collider stay aligned; see msw-general/references/monster.md

Native AIChaseComponent / AIWanderComponent
Engine flips automatically based on movement — do nothing

Top-down (RectTile) movement
Decide per-axis: usually flip when dx > 0; sprites with up/down frames need the StateAnimationComponent action set instead

_EffectService:PlayEffect(...) should face right
Pass FlipX = true in the options table

Player-attached effect must follow the player's facing
Use SyncFlip = true in PlayEffect options, or read PlayerControllerComponent.LookDirectionX

Resource is authored facing right (rare)
Inspect payload.thumbnail via GET /v3/resources/{ruid} and invert the rule for that asset

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

Keyword choice — Use the exact name if you know it; natural-language Korean/English also works.

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.

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.

Composite queries are allowed — e.g. AttackComponent CalcCritical for docs, red slime jump for resources.

No guessing — Never guess API names, RUIDs, or enum values; always confirm via search or references.