msw-search（都市固体废物搜寻）

MSW Search

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

1. API docs & implementation guides — Vector search that provides the details, code examples, related APIs, and implementation guidance that .d.mlua lacks.
2. Resources — REST API to search and browse sprites, animations, sounds, resource packs, and avatars. The only path for obtaining RUIDs.

Routing Table

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.

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

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 mapping: mlua_API_Retriever = type=api, mlua_Document_Retriever = type=document.

MCP Tool Usage

When msw-guide-mcp is connected:

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}

How to choose type

Usage Examples

# 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

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

Error Handling

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

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
@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":

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

Categories

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

Resource Routing Guide

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

1. Keyword choice — Use the exact name if you know it; natural-language Korean/English also works.
2. Adjust limit — Use a larger value (10+) for broad exploration, smaller (3) for precise lookups.
3. 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.

1. Composite queries are allowed — e.g. AttackComponent CalcCritical for docs, red slime jump for resources.
2. No guessing — Never guess API names, RUIDs, or enum values; always confirm via search or references.