MSW Search

MSW has two distinct search targets. They behave differently, so they are covered in separate sections.

API docs & implementation guides — Vector search that provides the details, code examples, related APIs, and implementation guidance that
```
.d.mlua
```
lacks.
Resources — REST API to search and browse 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 ( `type=both` )
"Implementation guide / best practice / pattern"	Document search ( `type=document` )
"I need a SpriteRUID", "Find a sprite for monster / NPC / background"	Resource search
"Find an animation / sound / resource pack"	Resource search
"Details for this RUID", "Similar resources"	Resource search
"Avatar rendering / default avatar"	Resource search

Section 1 — Document Search (APIs & Guides)

Vector search that supplies the detailed descriptions, code examples, related APIs, and implementation guides missing from

.d.mlua

Access Methods

The same vector search backend can be accessed through two paths. Results are identical.

Method	Condition	Usage
MCP tool	`msw-guide-mcp` is connected	Call `mlua_Document_Retriever` , `mlua_API_Retriever`
Direct curl	Fallback when MCP is not connected	`curl "http://10.10.200.51:31817/search?q=...&type=...&limit=..."`

Decision Flow

Need API-related information
│
├─ Checking signature / type / property / enum
│   → Read .d.mlua first (highest priority)
│   → If .d.mlua is insufficient, use vector search
│     (code examples, parameter details, related APIs, etc.)
│
├─ Implementation guide / pattern / best practice
│   → Vector search (type=document)
│
├─ Don't know the API name (semantic search)
│   → Vector search (type=both)
│
└─ How to access vector search:
    ├─ msw-guide-mcp connected? → MCP tool
    └─ Not connected → curl

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	Search type	Example query
Need a code example	`api`	`AIComponent example` , `BehaviorTree usage`
Parameter details	`api`	`BadgeService GetBadgeInfosAndWait parameters`
Related API cross-references	`api`	`AttackComponent related` , `HitComponent`
ScriptOverridable check	`api`	`AttackComponent CalcCritical override`
Don't know the API name	`both`	`damage calculation` , `inventory save`
"How do I …?" implementation guide	`document`	`how to make inventory system`
Pattern / best practice	`document`	`collision detection best practice`

MCP mapping:

mlua_API_Retriever

type=api

mlua_Document_Retriever

type=document

MCP Tool Usage

When

msw-guide-mcp

is connected:

Tool	Maps to type	Description
`mlua_API_Retriever`	`api`	API details for Service / Component / Misc etc. (signatures, parameters, examples)
`mlua_Document_Retriever`	`document`	Authoring manuals, guidelines, MLua usage, and other document-style material

Tool names and parameters follow the latest MCP schema.

Connection check: If a tool call errors out, it is not connected — fall back to curl.

Direct curl Usage

When

msw-guide-mcp

is not connected:

GET http://10.10.200.51:31817/search?q={query}&type={type}&limit={limit}

Parameter	Required	Value	Description
`q`	O	string	Search query (natural language or API name)
`type`	X	`api` \| `document` \| `both`	Search scope (default: `both` )
`limit`	X	integer	Max results (default: 5)

How to choose

type

Intent	type
Specific API spec (parameters, return type, example)	`api`
Implementation guidance (how-to, tutorial, concept)	`document`
Ambiguous or broad scope	`both`

Usage Examples

bash

# Specific API details + example
curl "http://10.10.200.51:31817/search?q=AIComponent&type=api&limit=5"

# Implementation guide
curl "http://10.10.200.51:31817/search?q=how+to+make+an+inventory+system&type=document&limit=5"

# Semantic search (when exact API name is unknown)
curl "http://10.10.200.51:31817/search?q=collision+detection&type=both&limit=10"

Response Format

json

{
  "results": "formatted text with matching documents (title, section, content)"
}

Error Handling

Code	Meaning	Action
`503`	Service is starting up	Retry after a short wait
`500`	Internal error (OpenSearch)	Fall back to `.d.mlua` files
Connection failure	Service not running	Fall back to `.d.mlua` files

.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	`[server only]` or omitted	`@ExecSpace("ServerOnly")`	Annotation must be explicit
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.

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
}

lua

-- Converted to .mlua
@ExecSpace("ServerOnly")
method integer CalcDamage(Entity attacker, Entity defender, string attackInfo)
    return 50
end

@ExecSpace("ServerOnly")
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.

Base URL

https://resourcesearch-api.future.msw.nxdev.kr

No authentication (public API)
All endpoints use the
```
/v3/
```
prefix
Content-Type:
```
application/json; charset=utf-8
```
(for POST requests)
Recommended timeout: 15 seconds

POST body rule — always use a temp file, never inline
-d '...'

For every POST endpoint in this section (

/v3/search/resources

/v3/resources/batch

/v3/avatar/render

), write the JSON body to a temp file first and call curl with

--data-binary "@file"

bash

REQ="$TMPDIR/msw_req.json"
cat > "$REQ" <<'JSON'
{ "query": "주황버섯", "types": ["resource_pack"], "categories": ["mob"], "limit": 5 }
JSON

curl -s -X POST https://resourcesearch-api.future.msw.nxdev.kr/v3/search/resources \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary "@$REQ"

Why: passing JSON inline (

-d '{"query":"주황버섯",...}'

) frequently breaks on non-ASCII input (Korean / Japanese / Chinese / emoji). The shell re-encodes the argument and the server returns:

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

The temp-file pattern also sidesteps the extra quoting/escaping required on Windows (PowerShell, Git Bash). Apply it uniformly even when the body is ASCII-only, so the recipe stays identical across platforms and languages.

On Windows PowerShell, use

$env:TEMP\msw_req.json

instead of

$TMPDIR/msw_req.json

and write the file with

Set-Content -Encoding utf8

(or

Out-File -Encoding utf8

). The

--data-binary "@file"

part is unchanged.

Resource Types

type	Description
`sprite`	Static image (PNG)
`animationclip`	Frame-based animation
`resource_pack`	Finished asset bundling sprites + animations + sounds
`sound`	Sound / audio clip

category	Description
`mob`	Monster
`npc`	NPC
`map`	Map / background / terrain
`item`	Item
`effect`	Effect
`skill`	Skill
`ui`	UI element

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

json

{
  "id": "32-char hex RUID",
  "type": "sprite|animationclip|resource_pack|sound",
  "category": "mob|npc|map|item|effect|skill|ui",
  "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": []
  }
}

Endpoint Summary

Method	Endpoint	Purpose
POST	`/v3/search/resources`	Natural-language semantic search
GET	`/v3/search/resources/similar/{ruid}`	Find similar resources
GET	`/v3/resources/{ruid}`	Single resource details
POST	`/v3/resources/batch`	Batch fetch multiple resources
GET	`/v3/resources/tags/{ruid}`	AI-generated multilingual tags
GET	`/v3/resources`	List by type / category
GET	`/v3/resources/random`	Random resource recommendation
GET	`/v3/resources/packs/{pack_id}`	Resource pack details + components
GET	`/v3/avatars/defaults`	Default avatar body / head RUIDs
GET	`/v3/avatars/{ruid}`	Avatar item details
POST	`/v3/avatar/render`	Render an avatar

Resource Routing Guide

Situation	Endpoint to use	Reference file
"Find a slime sprite"	`POST /v3/search/resources`	`references/resource/search.md`
"Any more monsters like this one?"	`GET /v3/search/resources/similar/{ruid}`	`references/resource/search.md`
"Details for RUID abc123"	`GET /v3/resources/{ruid}`	`references/resource/detail.md`
"Show me a list of monster sprites"	`GET /v3/resources`	`references/resource/browse.md`
"What's inside this resource pack?"	`GET /v3/resources/packs/{pack_id}`	`references/resource/browse.md`
"Render an avatar"	`POST /v3/avatar/render`	`references/resource/avatar.md`

Typical Workflow

1. Semantic search (POST /v3/search/resources) → obtain RUID
2. Detail lookup (GET /v3/resources/{ruid}) → inspect payload
3. For resource packs → pack details (GET /v3/resources/packs/{pack_id}) → individual element RUIDs
4. Assign the individual RUID to SpriteRendererComponent.SpriteRUID

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

Shared Tips

Keyword choice — Use the exact name if you know it; natural-language Korean/English also works.
Adjust
limit
— Use a larger value (10+) for broad exploration, smaller (3) for precise lookups.
When search fails:
- Document search fails → read
```
.d.mlua
```
  directly and check
```
mod/APIMetadata/
```
  JSON.
- Resource search fails → retry with synonyms or a different category; browse with
```
GET /v3/resources
```
  by type/category.
- ```
POST
```
  returns
```
{"detail":"There was an error parsing the body"}
```
  → you almost certainly used inline
```
-d '{...}'
```
  with a non-ASCII value. Switch to the temp-file pattern (
```
--data-binary "@file"
```
  ) 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.

msw-search

NPX Install

Tags

SKILL.md Content

MSW Search

Routing Table

Section 1 — Document Search (APIs & Guides)

Access Methods

Decision Flow

API Research Order

Priority 1 — .d.mlua (always first)

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

MCP Tool Usage

Direct curl Usage

How to choose
`type`

Usage Examples

Response Format

Error Handling

.d.mlua vs Search — Information Comparison

Maker Editor Syntax → .mlua Conversion Rules

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

Base URL

POST body rule — always use a temp file, never inline
`-d '...'`

Resource Types

Categories

RUID

Common Response Fields

Endpoint Summary

Resource Routing Guide

Typical Workflow

Shared Tips

msw-search

NPX Install

Tags

SKILL.md Content

MSW Search

Routing Table

Section 1 — Document Search (APIs & Guides)

Access Methods

Decision Flow

API Research Order

Priority 1 — .d.mlua (always first)

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

MCP Tool Usage

Direct curl Usage

How to choose type

Usage Examples

Response Format

Error Handling

.d.mlua vs Search — Information Comparison

Maker Editor Syntax → .mlua Conversion Rules

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

Base URL

POST body rule — always use a temp file, never inline -d '...'

Resource Types

Categories

RUID

Common Response Fields

Endpoint Summary

Resource Routing Guide

Typical Workflow

Shared Tips

How to choose
`type`

POST body rule — always use a temp file, never inline
`-d '...'`