msw-costume（城市固体废物服装）

MSW 코스튬 (CostumeManager)

아바타 장비·코스튬은 MOD.Core.CostumeManagerComponent가 담당한다. 예전 Maker RPC(get_costume / set_costume)는 사용하지 않는다. 워크스페이스 파일을 직접 편집하고, 변경이 에디터에 반영되도록 msw-maker-mcp의 refresh 도구를 호출한다.

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

작업 대상별 편집 위치

조회(get에 해당): 위 파일을 읽어 CostumeManagerComponent 관련 필드·Values 항목을 확인한다. Maker MCP가 연결되어 있다면 get_component로 런타임/에디터 스냅샷을 보조 조회할 수 있다(msw-maker-mcp 스킬 참고).

적용(set에 해당): 파일에 값을 쓴 뒤 refresh 호출.

변경 반영: MCP refresh

파일 저장 후 반드시 msw-maker-mcp 서버의 refresh 도구를 호출하여 Maker와 비주얼 상태를 동기화한다. (msw-maker-mcp 스킬의 도구 목록 참고)

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로 접근한다.

기타 동기화 프로퍼티

17 슬롯 ↔ 프로퍼티 ↔ MapleAvatarItemCategory

CostumeManagerComponent의 장비 문자열 필드 17개와 엔진 enum MapleAvatarItemCategory 대응이다. (enum 정의: Environment/NativeScripts/Enum/MapleAvatarItemCategory.d.mlua 등 참고)

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

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

1. 롱코트 ↔ 코트 + 바지 Longcoat는 설계상 코트(Coat)와 바지(Pants) 슬롯을 함께 사용한다. 롱코트를 착용시키면 롱코트 RUID는 CustomLongcoatEquip에 두고, 상·하의를 따로 보이게 하려면 코트/바지와의 조합을 논리적으로 정리한다(통상 롱코트 사용 시 코트·바지 개별 장비는 비우거나 충돌을 피한다).
2. 두손 무기 ↔ 한손 무기 + 보조 TwoHandedWeapon은 한손 무기 슬롯과 보조 무기 슬롯을 함께 쓴다. 두손 무기를 쓰면 CustomTwoHandedWeaponEquip를 중심으로 맞추고, 한손·보조와의 이중 장착이 되지 않게 값을 정리한다.
3. 방패(Shield) ↔ 보조 무기 Shield는 보조 무기 슬롯을 쓴다. CustomSubWeaponEquip와 동시에 다른 보조 장비를 기대하지 않도록 한다.
4. 빈 문자열로 해제 스크립트 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는 검색으로 치환)

{
  "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 예시

{
  "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/ 아래 해당 맵의 엔티티 레코드를 연다.

1. ContentProto.Entities 배열에서 대상 엔티티(이름·path·id로 식별)를 찾는다.
2. jsonString["@components"] 배열에서 "@type": "MOD.Core.CostumeManagerComponent" 인 객체를 찾는다.
3. 그 객체의 **Custom*Equip, UseCustomEquipOnly, DefaultEquipUserId** 등을 직접 수정한다.
4. componentNames 문자열 목록에 MOD.Core.CostumeManagerComponent가 포함되어 있는지 확인하고, 컴포넌트 배열과 불일치하면 안 된다.

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

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

GET /v3/avatars로 얻은 아이템의 category 필드를 Custom*Equip 프로퍼티에 매핑한다. 검색 방법은 msw-search 스킬 → references/resource/avatar.md 참조.

아바타 리소스 검색 참고

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

관련 스킬

요약 체크리스트

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