msw-search

What this skill does

# 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"](../msw-scripting/SKILL.md).

**Conversion example** — AttackComponent from search results:

```
-- Maker Editor syntax (search result)
override int CalcDamag