MSW 코스튬 (CostumeManager)

아바타 장비·코스튬은 **

MOD.Core.CostumeManagerComponent

**가 담당한다. 예전 Maker RPC(

get_costume

set_costume

)는 사용하지 않는다. 워크스페이스 파일을 직접 편집하고, 변경이 에디터에 반영되도록 msw-maker-mcp
의
refresh
도구를 호출한다.

워크스페이스 경로 규칙: 맵
./map/
, UI
./ui/
, 스크립트·기타 에셋
./RootDesk/MyDesk/
, DefaultPlayer·Player 등 글로벌 모델
./Global/

작업 대상별 편집 위치

대상	편집 파일	비고
DefaultPlayer	`./Global/DefaultPlayer.model`	`Values` 배열에서 `CostumeManagerComponent` 프로퍼티 오버라이드
Player (베이스)	`./Global/Player.model`	보통 코스튬 기본값은 여기보다 DefaultPlayer.model에서 오버라이드
맵에 배치된 엔티티 (NPC, 몬스터 등)	`./map/{맵명}.map`	해당 엔티티의 `jsonString.@components` 내 `CostumeManagerComponent` 블록
커스텀 모델만 참조하는 엔티티	해당 `.model` (예: `./RootDesk/MyDesk/` 등)	맵에 인라인 컴포넌트가 없고 `modelId` 로만 묶인 경우 모델 쪽을 수정

조회(get에 해당): 위 파일을 읽어

CostumeManagerComponent

RUID(리소스 고유 ID)

코스튬에 넣는 문자열은 아바타 아이템의 RUID(일반적으로 32자 hex)이다.

RUID를 추측·임의 생성하면 안 된다.
```
msw-search
```
스킬 및 references/avatar.md
(기본 body/head, 아이템 상세, 렌더 조합),
```
references/search.md
```
,
```
references/detail.md
```
등으로 검색·조회하여 확보한다.
스크립트 API
```
SetEquip(MapleAvatarItemCategory, itemRUID)
```
와 동일하게, 에디터/모델에 저장하는 것도 결국 같은 RUID 문자열이다.

CostumeManagerComponent 개요

플레이어·NPC 등 아바타를 쓰는 엔티티에 부착된다. 장비 슬롯은 커스텀 장비용 문자열 프로퍼티 17개(

Custom*Equip

)로 표현되며, 스크립트에서는

GetEquip

SetEquip

과

MapleAvatarItemCategory

로 접근한다.

기타 동기화 프로퍼티

프로퍼티	타입	설명
UseCustomEquipOnly	`boolean` (기본 `false` )	`true` 이면 유저 계정 기본 코스튬을 쓰지 않고, 스크립트·모델에 지정한 코스튬만 사용한다. 월드에서 외형을 고정할 때 중요하다.
DefaultEquipUserId	`string`	지정한 유저의 장비를 복제한 뒤, 그 위에 커스텀 장비를 얹는 방식. 접속하지 않은 유저도 지정 가능. 대상 유저가 이후 장비를 바꾸면 반영이 달라질 수 있다.
EquippedItems	읽기 전용	런타임에서 실제 장착 정보. 스크립트에서 수정 불가.

17 슬롯 ↔ 프로퍼티 ↔ MapleAvatarItemCategory

CostumeManagerComponent

의 장비 문자열 필드 17개와 엔진 enum MapleAvatarItemCategory
대응이다. (enum 정의:

Environment/NativeScripts/Enum/MapleAvatarItemCategory.d.mlua

등 참고)

#	컴포넌트 프로퍼티 (문자열 RUID)	MapleAvatarItemCategory	비고
1	CustomBodyEquip	Body (1)	스킨/바디
2	CustomHairEquip	Hair (3)	헤어
3	CustomFaceEquip	Face (4)	성형/페이스
4	CustomCapEquip	Cap (5)	모자
5	CustomCapeEquip	Cape (6)	망토
6	CustomCoatEquip	Coat (7)	상의(코트)
7	CustomLongcoatEquip	Longcoat (9)	롱코트 — 상의+하의 슬롯을 함께 쓰는 아이템 분류
8	CustomPantsEquip	Pants (10)	하의
9	CustomGloveEquip	Glove (8)	장갑
10	CustomShoesEquip	Shoes (12)	신발
11	CustomOneHandedWeaponEquip	OneHandedWeapon (13)	한손 무기
12	CustomTwoHandedWeaponEquip	TwoHandedWeapon (14)	두손 무기 — 한손 무기 + 보조 무기 슬롯을 함께 쓰는 분류
13	CustomSubWeaponEquip	SubWeapon (15)	보조 무기
14	CustomFaceAccessoryEquip	FaceAccessory (16)	페이스 악세
15	CustomEyeAccessoryEquip	EyeAccessory (17)	눈 악세
16	CustomEarAccessoryEquip	EarAccessory (18)	귀 악세
17	CustomEarEquip	Ear (19)	귀(신체 파츠)

enum에만 있고 위 17필드에 직접 대응하지 않는 항목

MapleAvatarItemCategory	설명
Head (2)	“장비로 쓰지 않음”에 가깝고 바디 색에 맞춰 자동 처리되는 분류. `CustomHeadEquip` 같은 필드는 없다.
Invalid (0)	오류/미정의 검출용.
Shield (11)	enum 주석상 보조 무기 슬롯(SubWeapon) 을 사용. 실질 저장은 CustomSubWeaponEquip 쪽과 배타적으로 정리하는 것이 안전하다.

상호 배타·슬롯 점유 규칙 (필수 이해)

롱코트 ↔ 코트 + 바지
Longcoat는 설계상 코트(Coat)와 바지(Pants) 슬롯을 함께 사용한다. 롱코트를 착용시키면 롱코트 RUID는
CustomLongcoatEquip
에 두고, 상·하의를 따로 보이게 하려면 코트/바지와의 조합을 논리적으로 정리한다(통상 롱코트 사용 시 코트·바지 개별 장비는 비우거나 충돌을 피한다).
두손 무기 ↔ 한손 무기 + 보조
TwoHandedWeapon은 한손 무기 슬롯과 보조 무기 슬롯을 함께 쓴다. 두손 무기를 쓰면 CustomTwoHandedWeaponEquip를 중심으로 맞추고, 한손·보조와의 이중 장착이 되지 않게 값을 정리한다.
방패(Shield) ↔ 보조 무기
Shield는 보조 무기 슬롯을 쓴다. CustomSubWeaponEquip와 동시에 다른 보조 장비를 기대하지 않도록 한다.
빈 문자열로 해제
스크립트
```
SetEquip(category, "")
```
와 같이, 파일에서도 ""
로 두면 해당 슬롯 해제로 이해하면 된다.

DefaultPlayer.model —

Values

에 코스튬 넣기

./Global/DefaultPlayer.model

의 ContentProto.Json.Values
배열에 항목을 추가하거나 기존 항목을 수정한다.

TargetType:
```
"MOD.Core.CostumeManagerComponent"
```
Name: 위 표의 프로퍼티 이름 (예:
```
CustomCapEquip
```
,
```
UseCustomEquipOnly
```
)
ValueType: 기존
```
DefaultPlayer.model
```
의 다른
```
Values
```
항목과 동일한 패턴을 따른다. 문자열은
```
System.String, mscorlib, ...
```
, 불리언은
```
System.Boolean, mscorlib, ...
```
Value: RUID 문자열 또는
```
true
```
/
```
false
```

동일

(TargetType, Name)

가 이미 있으면 그 항목만 갱신하고, 없으면 배열에 객체 하나 추가한다.

문자열 슬롯 예시 (구조만 참고; RUID는 검색으로 치환)

json

{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "CustomCapEquip",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": "여기에_32자hex_RUID"
}

UseCustomEquipOnly 예시

json

{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "UseCustomEquipOnly",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": true
}

맵 엔티티 —

.map

파일에서 수정

./map/

아래 해당 맵의 엔티티 레코드를 연다.

```
ContentProto.Entities
```
배열에서 대상 엔티티(이름·path·id로 식별)를 찾는다.

jsonString["@components"]

배열에서 "@type": "MOD.Core.CostumeManagerComponent"
인 객체를 찾는다.

그 객체의 Custom*Equip
, UseCustomEquipOnly
, DefaultEquipUserId
등을 직접 수정한다.

componentNames
문자열 목록에
```
MOD.Core.CostumeManagerComponent
```
가 포함되어 있는지 확인하고, 컴포넌트 배열과 불일치하면 안 된다.

맵이 바이너리 포맷만 쓰는 경우 등은 워크스페이스 정책에 따라 편집 도구가 다를 수 있다. JSON 텍스트로 열리는 경우 위 구조를 따른다.

GET /v3/avatars 검색 결과 → 슬롯 매핑

GET /v3/avatars

로 얻은 아이템의

category

필드를

Custom*Equip

프로퍼티에 매핑한다. 검색 방법은

msw-search

스킬 →

references/resource/avatar.md

참조.

API `category`	`Custom*Equip` 프로퍼티	`MapleAvatarItemCategory`
`body`	`CustomBodyEquip`	Body (1)
`hair`	`CustomHairEquip`	Hair (3)
`face`	`CustomFaceEquip`	Face (4)
`faceaccessory`	`CustomFaceAccessoryEquip`	FaceAccessory (16)
`eyeaccessory`	`CustomEyeAccessoryEquip`	EyeAccessory (17)
`earaccessory`	`CustomEarAccessoryEquip`	EarAccessory (18)
`cap`	`CustomCapEquip`	Cap (5)
`cape`	`CustomCapeEquip`	Cape (6)
`longcoat`	`CustomLongcoatEquip`	Longcoat (9)
`coat`	`CustomCoatEquip`	Coat (7)
`pants`	`CustomPantsEquip`	Pants (10)
`glove`	`CustomGloveEquip`	Glove (8)
`shoes`	`CustomShoesEquip`	Shoes (12)
`weapon`	`CustomOneHandedWeaponEquip`	OneHandedWeapon (13)
`twohandweapon`	`CustomTwoHandedWeaponEquip`	TwoHandedWeapon (14)
`subweapon`	`CustomSubWeaponEquip`	SubWeapon (15)
`shield`	`CustomSubWeaponEquip`	Shield (11) — SubWeapon 슬롯 공유

아바타 리소스 검색 참고

msw-search
스킬 →
```
references/resource/avatar.md
```
:
```
GET /v3/avatars
```
(코스튬 검색), 기본 body/head,
```
GET /v3/avatars/{ruid}
```
, 렌더 조합 등 아바타 파이프라인 상세.
장비 RUID는 카테고리 검색·상세 API를 병행해 확보한다.

스킬	용도
msw-defaultplayer	`./Global/DefaultPlayer.model` · `Player.model` 구조, `Values` 규칙
msw-search	RUID 검색, `references/resource/avatar.md`
msw-maker-mcp	`refresh` , 필요 시 `get_component` / `set_property` (런타임 조정과 병행 시)

요약 체크리스트

RUID는 resource 검색·avatar 참고 문서로 확보한다.
DefaultPlayer/Player →
```
./Global/*.model
```
의 Values
또는 베이스 모델 정의.
맵 엔티티 →
```
./map/*.map
```
의 해당 엔티티 @components
.
롱코트 / 두손 무기 / 방패·보조 배타 규칙을 지킨다.
**
```
UseCustomEquipOnly
```
**로 “계정 기본 코스튬 무시” 여부를 명시한다.
저장 후 msw-maker-mcp
→
refresh
호출.

msw-costume

NPX Install

Tags

SKILL.md Content

MSW 코스튬 (CostumeManager)

작업 대상별 편집 위치

변경 반영: MCP
`refresh`

RUID(리소스 고유 ID)

CostumeManagerComponent 개요

기타 동기화 프로퍼티

17 슬롯 ↔ 프로퍼티 ↔ MapleAvatarItemCategory

enum에만 있고 위 17필드에 직접 대응하지 않는 항목

상호 배타·슬롯 점유 규칙 (필수 이해)

DefaultPlayer.model —
`Values`
에 코스튬 넣기

문자열 슬롯 예시 (구조만 참고; RUID는 검색으로 치환)

UseCustomEquipOnly 예시

맵 엔티티 —
`.map`
파일에서 수정

GET /v3/avatars 검색 결과 → 슬롯 매핑

아바타 리소스 검색 참고

관련 스킬

요약 체크리스트

msw-costume

NPX Install

Tags

SKILL.md Content

MSW 코스튬 (CostumeManager)

작업 대상별 편집 위치

변경 반영: MCP refresh

RUID(리소스 고유 ID)

CostumeManagerComponent 개요

기타 동기화 프로퍼티

17 슬롯 ↔ 프로퍼티 ↔ MapleAvatarItemCategory

enum에만 있고 위 17필드에 직접 대응하지 않는 항목

상호 배타·슬롯 점유 규칙 (필수 이해)

DefaultPlayer.model — Values에 코스튬 넣기

문자열 슬롯 예시 (구조만 참고; RUID는 검색으로 치환)

UseCustomEquipOnly 예시

맵 엔티티 — .map 파일에서 수정

GET /v3/avatars 검색 결과 → 슬롯 매핑

아바타 리소스 검색 참고

관련 스킬

요약 체크리스트

변경 반영: MCP
`refresh`

DefaultPlayer.model —
`Values`
에 코스튬 넣기

맵 엔티티 —
`.map`
파일에서 수정