Back to Details

msw-costume

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MSW 코스튬 (CostumeManager)

MSW 服装（CostumeManager）

아바타 장비·코스튬은 **
MOD.Core.CostumeManagerComponent
**가 담당한다. 예전 Maker RPC(
get_costume
/ 
set_costume
)는 사용하지 않는다. 워크스페이스 파일을 직접 편집하고, 변경이 에디터에 반영되도록 
msw-maker-mcp
의 
refresh
도구를 호출한다.
워크스페이스 경로 규칙: 맵 
./map/
, UI 
./ui/
, 스크립트·기타 에셋 
./RootDesk/MyDesk/
, DefaultPlayer·Player 등 글로벌 모델 
./Global/
Avatar装备与服装由**
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
관련 필드·
Values
항목을 확인한다. Maker MCP가 연결되어 있다면 
get_component
로 런타임/에디터 스냅샷을 보조 조회할 수 있다(
msw-maker-mcp
스킬 참고).
적용(set에 해당): 파일에 값을 쓴 뒤 
refresh
 호출.
对象编辑文件备注
DefaultPlayer
./Global/DefaultPlayer.model
在
Values
数组中覆盖
CostumeManagerComponent
属性
Player（基础版）
./Global/Player.model
通常服装默认值优先在DefaultPlayer.model中覆盖
地图中放置的实体（NPC、怪物等）
./map/{地图名}.map
在对应实体的
jsonString.@components
内的
CostumeManagerComponent
块中编辑
仅引用自定义模型的实体对应 
.model
文件（例如：
./RootDesk/MyDesk/
等）		若地图中无内联组件，仅通过
modelId
关联，则修改模型文件
查询（对应get操作）：读取上述文件，查看
CostumeManagerComponent
相关字段及
Values
项。若已连接Maker MCP，可通过
get_component
辅助查询运行时/编辑器快照（参考
msw-maker-mcp
技能）。
应用（对应set操作）：写入文件值后，调用**
refresh
**工具。

변경 반영: MCP 
refresh

变更同步：MCP 
refresh

파일 저장 후 반드시 
msw-maker-mcp
서버의 
refresh
 도구를 호출하여 Maker와 비주얼 상태를 동기화한다. (
msw-maker-mcp
스킬의 도구 목록 참고)
文件保存后必须调用
msw-maker-mcp
服务器的**
refresh
**工具，同步Maker与视觉状态（参考
msw-maker-mcp
技能的工具列表）。

RUID(리소스 고유 ID)

RUID（资源唯一ID）

코스튬에 넣는 문자열은 아바타 아이템의 RUID(일반적으로 32자 hex)이다.
  • RUID를 추측·임의 생성하면 안 된다. 
    msw-search
    스킬 및 
    references/avatar.md
    (기본 body/head, 아이템 상세, 렌더 조합), 
    references/search.md
    , 
    references/detail.md
    등으로 검색·조회하여 확보한다.
  • 스크립트 API 
    SetEquip(MapleAvatarItemCategory, itemRUID)
    와 동일하게, 에디터/모델에 저장하는 것도 결국 같은 RUID 문자열이다.
服装中填写的字符串为Avatar物品的RUID（通常为32位十六进制字符串）。
  • 不得猜测或随意生成RUID。需通过
    msw-search
    技能及**
    references/avatar.md
    **（基础身体/头部、物品详情、渲染组合）、
    references/search.md
    、
    references/detail.md
    等文档查询获取。
  • 与脚本API 
    SetEquip(MapleAvatarItemCategory, itemRUID)
    相同，编辑器/模型中保存的也是相同的RUID字符串。

CostumeManagerComponent 개요

CostumeManagerComponent概述

플레이어·NPC 등 아바타를 쓰는 엔티티에 부착된다. 장비 슬롯은 커스텀 장비용 문자열 프로퍼티 17개(
Custom*Equip
)로 표현되며, 스크립트에서는 
GetEquip
/ 
SetEquip
과 
MapleAvatarItemCategory
로 접근한다.
该组件附加在玩家、NPC等使用Avatar的实体上。装备插槽通过17个自定义装备字符串属性（
Custom*Equip
）表示，脚本中可通过
GetEquip
/ 
SetEquip
及
MapleAvatarItemCategory
进行访问。

기타 동기화 프로퍼티

其他同步属性

프로퍼티타입설명
UseCustomEquipOnly
boolean
(기본 
false
)
true
이면 유저 계정 기본 코스튬을 쓰지 않고, 스크립트·모델에 지정한 코스튬만 사용한다. 월드에서 외형을 고정할 때 중요하다.
DefaultEquipUserId
string
지정한 유저의 장비를 복제한 뒤, 그 위에 커스텀 장비를 얹는 방식. 접속하지 않은 유저도 지정 가능. 대상 유저가 이후 장비를 바꾸면 반영이 달라질 수 있다.
EquippedItems읽기 전용런타임에서 실제 장착 정보. 스크립트에서 수정 불가.
属性类型说明
UseCustomEquipOnly
boolean
（默认
false
）		设为
true
时，不使用用户账号默认服装，仅使用脚本/模型中指定的服装。在固定世界外观时非常重要。
DefaultEquipUserId
string
先复制指定用户的装备，再在其基础上叠加自定义装备的方式。未登录用户也可指定。若目标用户后续修改装备，可能会影响当前设置。
EquippedItems只读运行时的实际装备信息。脚本无法修改。

17 슬롯 ↔ 프로퍼티 ↔ MapleAvatarItemCategory

17插槽 ↔ 属性 ↔ MapleAvatarItemCategory

CostumeManagerComponent
의 장비 문자열 필드 17개와 엔진 enum 
MapleAvatarItemCategory
 대응이다. (enum 정의: 
Environment/NativeScripts/Enum/MapleAvatarItemCategory.d.mlua
등 참고)
#컴포넌트 프로퍼티 (문자열 RUID)MapleAvatarItemCategory비고
1CustomBodyEquipBody (1)스킨/바디
2CustomHairEquipHair (3)헤어
3CustomFaceEquipFace (4)성형/페이스
4CustomCapEquipCap (5)모자
5CustomCapeEquipCape (6)망토
6CustomCoatEquipCoat (7)상의(코트)
7CustomLongcoatEquipLongcoat (9)롱코트 — 상의+하의 슬롯을 함께 쓰는 아이템 분류
8CustomPantsEquipPants (10)하의
9CustomGloveEquipGlove (8)장갑
10CustomShoesEquipShoes (12)신발
11CustomOneHandedWeaponEquipOneHandedWeapon (13)한손 무기
12CustomTwoHandedWeaponEquipTwoHandedWeapon (14)두손 무기 — 한손 무기 + 보조 무기 슬롯을 함께 쓰는 분류
13CustomSubWeaponEquipSubWeapon (15)보조 무기
14CustomFaceAccessoryEquipFaceAccessory (16)페이스 악세
15CustomEyeAccessoryEquipEyeAccessory (17)눈 악세
16CustomEarAccessoryEquipEarAccessory (18)귀 악세
17CustomEarEquipEar (19)귀(신체 파츠)
以下是
CostumeManagerComponent
的17个装备字符串字段与引擎枚举**
MapleAvatarItemCategory
**的对应关系。（枚举定义参考：
Environment/NativeScripts/Enum/MapleAvatarItemCategory.d.mlua
等）
序号组件属性（字符串RUID）MapleAvatarItemCategory备注
1CustomBodyEquipBody (1)皮肤/身体
2CustomHairEquipHair (3)发型
3CustomFaceEquipFace (4)脸型/面部
4CustomCapEquipCap (5)帽子
5CustomCapeEquipCape (6)披风
6CustomCoatEquipCoat (7)上衣（外套）
7CustomLongcoatEquipLongcoat (9)长款外套 — 占用上衣+下装插槽的物品分类
8CustomPantsEquipPants (10)下装
9CustomGloveEquipGlove (8)手套
10CustomShoesEquipShoes (12)鞋子
11CustomOneHandedWeaponEquipOneHandedWeapon (13)单手武器
12CustomTwoHandedWeaponEquipTwoHandedWeapon (14)双手武器 — 占用单手武器+辅助武器插槽的分类
13CustomSubWeaponEquipSubWeapon (15)辅助武器
14CustomFaceAccessoryEquipFaceAccessory (16)面部饰品
15CustomEyeAccessoryEquipEyeAccessory (17)眼部饰品
16CustomEarAccessoryEquipEarAccessory (18)耳部饰品
17CustomEarEquipEar (19)耳朵（身体部件）

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

仅存在于枚举中、无对应17字段的项

MapleAvatarItemCategory설명
Head (2)“장비로 쓰지 않음”에 가깝고 바디 색에 맞춰 자동 처리되는 분류. 
CustomHeadEquip
같은 필드는 없다.
Invalid (0)오류/미정의 검출용.
Shield (11)enum 주석상 보조 무기 슬롯(SubWeapon) 을 사용. 실질 저장은 CustomSubWeaponEquip 쪽과 배타적으로 정리하는 것이 안전하다.
MapleAvatarItemCategory说明
Head (2)近似“不可装备”分类，根据身体颜色自动处理，无
CustomHeadEquip
这类字段。
Invalid (0)用于检测错误/未定义项。
Shield (11)枚举注释中说明使用辅助武器插槽（SubWeapon），实际存储时建议与CustomSubWeaponEquip排他性处理以确保安全。

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

互斥·插槽占用规则（必须理解）

  1. 롱코트 ↔ 코트 + 바지
    Longcoat는 설계상 코트(Coat)와 바지(Pants) 슬롯을 함께 사용한다. 롱코트를 착용시키면 롱코트 RUID는 
    CustomLongcoatEquip
    에 두고    , 상·하의를 따로 보이게 하려면 코트/바지와의 조합을 논리적으로 정리한다(통상 롱코트 사용 시 코트·바지 개별 장비는 비우거나 충돌을 피한다).
  2. 두손 무기 ↔ 한손 무기 + 보조
    TwoHandedWeapon은 한손 무기 슬롯과 보조 무기 슬롯을 함께 쓴다. 두손 무기를 쓰면 CustomTwoHandedWeaponEquip를 중심으로 맞추고, 한손·보조와의 이중 장착이 되지 않게 값을 정리한다.
  3. 방패(Shield) ↔ 보조 무기
    Shield는 보조 무기 슬롯을 쓴다. CustomSubWeaponEquip와 동시에 다른 보조 장비를 기대하지 않도록 한다.
  4. 빈 문자열로 해제
    스크립트 
    SetEquip(category, "")
    와 같이, 파일에서도 
    ""
    로 두면 해당 슬롯 해제    로 이해하면 된다.
  1. 长款外套 ↔ 外套 + 下装
    Longcoat设计上同时占用外套（Coat）和下装（Pants）插槽。若装备长款外套，需将长款外套RUID存入
    CustomLongcoatEquip
    ；若要单独显示上衣和下装，需合理整理外套/下装的组合（通常使用长款外套时，需清空或避免与外套、下装单独装备冲突）。
  2. 双手武器 ↔ 单手武器 + 辅助武器
    TwoHandedWeapon同时占用单手武器插槽和辅助武器插槽。使用双手武器时，需以CustomTwoHandedWeaponEquip为核心配置，并确保不会同时装备单手武器和辅助武器。
  3. 盾牌（Shield） ↔ 辅助武器
    Shield占用辅助武器插槽，请勿期望同时使用CustomSubWeaponEquip与其他辅助装备。
  4. 空字符串解除装备
    与脚本
    SetEquip(category, "")
    相同，文件中设置为**
    ""
    即解除对应插槽的装备**。

DefaultPlayer.model — 
Values
에 코스튬 넣기

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)
가 이미 있으면 그 항목만 갱신하고, 없으면 배열에 객체 하나 추가한다.
在
./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는 검색으로 치환)

字符串插槽示例（仅参考结构；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"
}
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 예시

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
}
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
文件中修改

./map/
아래 해당 맵의 엔티티 레코드를 연다.
  1. ContentProto.Entities
    배열에서 대상 엔티티(이름·path·id로 식별)를 찾는다.
  2. jsonString["@components"]
    배열에서 
    "@type": "MOD.Core.CostumeManagerComponent"
     인 객체를 찾는다.
  3. 그 객체의 
    Custom*Equip
    , 
    UseCustomEquipOnly
    , 
    DefaultEquipUserId
     등을 직접 수정한다.
  4. componentNames
     문자열 목록에 
    MOD.Core.CostumeManagerComponent
    가 포함되어 있는지 확인하고, 컴포넌트 배열과 불일치하면 안 된다.
맵이 바이너리 포맷만 쓰는 경우 등은 워크스페이스 정책에 따라 편집 도구가 다를 수 있다. JSON 텍스트로 열리는 경우 위 구조를 따른다.
打开
./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搜索结果 → 插槽映射

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 슬롯 공유
将
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插槽

아바타 리소스 검색 참고

Avatar资源查询参考

  • msw-search
     스킬 → 
    references/resource/avatar.md
    : 
    GET /v3/avatars
    (코스튬 검색), 기본 body/head, 
    GET /v3/avatars/{ruid}
    , 렌더 조합 등 아바타 파이프라인 상세.
  • 장비 RUID는 카테고리 검색·상세 API를 병행해 확보한다.
  • **
    msw-search
    **技能 → 
    references/resource/avatar.md
    ：包含
    GET /v3/avatars
    （服装搜索）、基础身体/头部、
    GET /v3/avatars/{ruid}
    、渲染组合等Avatar流水线详情。
  • 装备RUID需结合分类搜索及详情API获取。

관련 스킬

相关技能

스킬용도
msw-defaultplayer
./Global/DefaultPlayer.model
·
Player.model
구조, 
Values
규칙
msw-searchRUID 검색, 
references/resource/avatar.md
msw-maker-mcp
refresh
, 필요 시 
get_component
/ 
set_property
(런타임 조정과 병행 시)
技能用途
msw-defaultplayer
./Global/DefaultPlayer.model
、
Player.model
结构，
Values
规则
msw-searchRUID查询，
references/resource/avatar.md
msw-maker-mcp**
refresh
**工具，必要时使用
get_component
/ 
set_property
（配合运行时调整）

요약 체크리스트

总结检查清单

  1. RUID는 resource 검색·avatar 참고 문서로 확보한다.
  2. DefaultPlayer/Player → 
    ./Global/*.model
    의 
    Values
     또는 베이스 모델 정의.
  3. 맵 엔티티 → 
    ./map/*.map
    의 해당 엔티티 
    @components
    .
  4. 롱코트 / 두손 무기 / 방패·보조 배타 규칙을 지킨다.
  5. **
    UseCustomEquipOnly
    **로 “계정 기본 코스튬 무시” 여부를 명시한다.
  6. 저장 후 
    msw-maker-mcp
    → 
    refresh
     호출.
  1. 通过资源查询·Avatar参考文档获取RUID。
  2. DefaultPlayer/Player → 修改
    ./Global/*.model
    的**
    Values
    **或基础模型定义。
  3. 地图实体 → 修改
    ./map/*.map
    中对应实体的**
    @components
    **。
  4. 遵守长款外套 / 双手武器 / 盾牌·辅助武器的互斥规则。
  5. 通过**
    UseCustomEquipOnly
    **明确是否“忽略账号默认服装”。
  6. 保存后调用**
    msw-maker-mcp
    → 
    refresh
    **工具。