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

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 (account_get_my_user_id first for ownerId)

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

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

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

...