msw-search

Original：🇺🇸 English
Translated

MSW search integration — (1) vector search for API docs and implementation guides (msw-guide-mcp or curl against mlua_Document_Retriever / mlua_API_Retriever), (2) REST API search for resources (sprite / animation / sound / resource pack / avatar). Use for 'find details, examples, or related APIs not in .d.mlua', 'need a SpriteRUID', 'monster sprite', 'background image', 'find a sound', 'avatar rendering', etc. Keywords: document search, API details, examples, guide, retriever, resource, sprite, animation, sound, RUID, resource pack, avatar.

7installs
Sourcemsw-git/msw-ai-coding-plugins-official
Added on

NPX Install

npx skill4agent add msw-git/msw-ai-coding-plugins-official msw-search

Tags

Translated version includes tags in frontmatter
msw-searchvector-searchresource-searchapi-documentationrest-api

SKILL.md Content

View Translation Comparison →

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

Request typeGo 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.
MethodConditionUsage
MCP tool
msw-guide-mcp
is connected		Call 
mlua_Document_Retriever
, 
mlua_API_Retriever
Direct curlFallback 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
SituationExample
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.
SituationSearch typeExample 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:
ToolMaps to typeDescription
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}
ParameterRequiredValueDescription
q
OstringSearch query (natural language or API name)
type
X
api
| 
document
| 
both
Search scope (default: 
both
)
limit
XintegerMax results (default: 5)

How to choose 
type

Intenttype
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

CodeMeaningAction
503
Service is starting upRetry after a short wait
500
Internal error (OpenSearch)Fall back to 
.d.mlua
files
Connection failureService not runningFall 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.mluaSearch
Method signature / typesOO
Property declarationsOO
Detailed method description (DetailDesc)XO
Code examples (AdditionalPageContent)XO
Per-parameter descriptionsXO
Related APIs (SeeAlsoAPIs)XO
Related guides (SeeAlsoGuides)XO
ScriptOverridable flagXO
SyncDirectionPartialO
Localized descriptions (Ko/Ja/Es/Zh)XO

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.
ItemMaker Editor.mlua fileNote
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

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

Categories

categoryDescription
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

MethodEndpointPurpose
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

SituationEndpoint to useReference 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

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