Avatar equipment and costumes are handled by **MOD.Core.CostumeManagerComponent**. The old Maker RPC (get_costume / set_costume) is not used. Edit workspace files directly, and so that changes are reflected in the editor, msw-maker-mcp의 refresh toolis called.
Workspace path rules: 맵
./map/, UI./ui/, scripts and other assets./RootDesk/MyDesk/, global models such as DefaultPlayer and Player./Global/
Edit location per work target
| Target | Edit file | Notes |
|---|---|---|
| DefaultPlayer | ./Global/DefaultPlayer.model |
Values in the array, CostumeManagerComponent property override |
| Player (base) | ./Global/Player.model |
Usually costume defaults are overridden here rather than DefaultPlayer.modelin |
| Entities placed in the map (NPCs, monsters, etc.) | ./map/{맵명}.map |
That entity's jsonString.@components 내 CostumeManagerComponent block |
| Entities that reference only a custom model | That .model (예: ./RootDesk/MyDesk/ 등) |
If the map has no inline component and is bound only by modelId, modify the model side |
Lookup (corresponds to get): Read the above file and check CostumeManagerComponent related fields andValues items. If Maker MCP is connected, get_componentcan be used to assist in looking up runtime/editor snapshots (msw-maker-mcp see skill).
Apply (corresponds to set): After writing the value to the file, refresh call.
Reflect changes: MCP refresh
After saving the file, must msw-maker-mcp call the server's refresh tool to synchronize Maker and the visual state. (msw-maker-mcp see the tool list in the skill)
RUID (resource unique ID)
The string put into the costume is the avatar item's RUID(generally a 32-character hex).
- RUID를 Must not be guessed or arbitrarily generated.
msw-searchskill andreferences/avatar.md(default body/head, item details, render composition),references/search.md,references/detail.mdetc. to search and look up and obtain it. - Script API
SetEquip(MapleAvatarItemCategory, itemRUID)Same as, saving to the editor/model is ultimately the same RUID stringis.
CostumeManagerComponent overview
Players, NPCs, etc. entities that use avatarsis attached to. Equipment slots are 17 string properties for custom equipment(Custom*Equip), and in scripts it is accessed as GetEquip / SetEquip과 MapleAvatarItemCategory.
Other synchronization properties
| Property | Type | Description |
|---|---|---|
| UseCustomEquipOnly | boolean (default false) |
trueif true, Without using the user account's default costume,, only the costumes specified in the script/model are used. This is important when fixing appearance in a world. |
| DefaultEquipUserId | string |
The specified user's equipment is after cloning, and then layering custom equipment on top of it. Users who are not connectedcan also be specified. If the target user later changes equipment, the reflection may differ. |
| EquippedItems | Read-only | Actual equipped information at runtime. Cannot be modified from scripts. |
17 slots ↔ properties ↔ MapleAvatarItemCategory
CostumeManagerComponent의 17 equipment string fieldsand the engine enum MapleAvatarItemCategory correspondence. (enum definitions: Environment/NativeScripts/Enum/MapleAvatarItemCategory.d.mlua etc. reference)
| # | Component properties (string RUID) | MapleAvatarItemCategory | Remarks |
|---|---|---|---|
| 1 | CustomBodyEquip | Body (1) | Skin/Body |
| 2 | CustomHairEquip | Hair (3) | Hair |
| 3 | CustomFaceEquip | Face (4) | Face |
| 4 | CustomCapEquip | Cap (5) | Hat |
| 5 | CustomCapeEquip | Cape (6) | Cape |
| 6 | CustomCoatEquip | Coat (7) | Top (Coat) |
| 7 | CustomLongcoatEquip | Longcoat (9) | Longcoat — uses the top+bottom slots together item category |
| 8 | CustomPantsEquip | Pants (10) | Bottom |
| 9 | CustomGloveEquip | Glove (8) | Gloves |
| 10 | CustomShoesEquip | Shoes (12) | Shoes |
| 11 | CustomOneHandedWeaponEquip | OneHandedWeapon (13) | One-handed weapon |
| 12 | CustomTwoHandedWeaponEquip | TwoHandedWeapon (14) | Two-handed weapon — uses the one-handed weapon + secondary weapon slots together category |
| 13 | CustomSubWeaponEquip | SubWeapon (15) | Secondary weapon |
| 14 | CustomFaceAccessoryEquip | FaceAccessory (16) | Face accessory |
| 15 | CustomEyeAccessoryEquip | EyeAccessory (17) | Eye accessory |
| 16 | CustomEarAccessoryEquip | EarAccessory (18) | Ear accessory |
| 17 | CustomEarEquip | Ear (19) | Ear (body part) |
Items that exist only in the enum and do not directly correspond to the above 17 fields
| MapleAvatarItemCategory | Description |
|---|---|
| Head (2) | Closer to “not used as equipment,” and automatically matches the body color category that is processed. CustomHeadEquip There is no such field. |
| Invalid (0) | For detecting errors/undefined values. |
| Shield (11) | According to the enum comment, Secondary weapon slot (SubWeapon) is used. For actual storage, it is safer to organize it exclusively with CustomSubWeaponEquip . |
Mutual exclusion/slot occupancy rules (essential understanding)
-
Longcoat ↔ Coat + Pants
Longcoatis by design uses the Coat and Pants slots together. When equipping a longcoat, the longcoat RUID isCustomLongcoatEquipplaced in, and to show top and bottom separately, logically organize the combination with coat/pants. (Normally, when using a longcoat, leave the individual coat and pants equipment empty or avoid conflicts.) -
Two-handed weapon ↔ One-handed weapon + Secondary
TwoHandedWeapon은 uses the one-handed weapon slot and secondary weapon slot together. When using a two-handed weapon, CustomTwoHandedWeaponEquipalign around it, and with one-handed/secondary so that dual equipping does not occur organize the values. -
Shield ↔ Secondary weapon
Shield는 Secondary weapon slotuses. CustomSubWeaponEquipand at the same time do not expect other secondary equipment. -
Clear with an empty string
ScriptSetEquip(category, "")as well as in the file,""if set to this, the corresponding slot is clearedcan be understood as.
DefaultPlayer.model — ValuesPut a costume in
./Global/DefaultPlayer.model의 ContentProto.Json.Values Add an item to the array or modify an existing item.
- TargetType:
"MOD.Core.CostumeManagerComponent" - Name: Property name from the table above (e.g.,
CustomCapEquip,UseCustomEquipOnly) - ValueType: Existing
DefaultPlayer.model's otherValuesfollows the same pattern as the item. Strings areSystem.String, mscorlib, ..., booleans areSystem.Boolean, mscorlib, ... - Value: RUID string or
true/false
If the same (TargetType, Name)already exists, update only that itemand, if not, add one object to the arraydoes.
String slot example (structure only for reference; replace RUID via search)
{
"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 example
{
"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 entity — .map Edit in the file
./map/ Below, the corresponding map's entity recordopen.
ContentProto.EntitiesIn the array, find the target entity (identified by name, path, id).jsonString["@components"]In the array,"@type": "MOD.Core.CostumeManagerComponent"find the object that is.- That object's
Custom*Equip,UseCustomEquipOnly,DefaultEquipUserIdetc. directly. componentNamesIn the string list,MOD.Core.CostumeManagerComponentcheck whether is included, and it must not conflict with the component array.
If the map uses only a binary format, etc., the editing tool may differ depending on workspace policy. If it opens as JSON text, follow the structure above.
GET /v3/avatars search results → slot mapping
GET /v3/avatarsof the item obtained with category field to the Custom*Equip property. For the search method, see msw-search skill → references/resource/avatar.md reference.
API category |
Custom*Equip property |
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) — Shares the SubWeapon slot |
See avatar resource search
msw-searchskill →references/resource/avatar.md:GET /v3/avatars(costume search), default body/head,GET /v3/avatars/{ruid}, rendering composition, and other avatar pipeline details.- Obtain equipment RUIDs by using both category search and detail APIs.
Related skills
| Skill | Purpose |
|---|---|
| msw-defaultplayer | ./Global/DefaultPlayer.model·Player.model structure, Values rules |
| msw-search | RUID search, references/resource/avatar.md |
| msw-maker-mcp | refresh, if needed get_component / set_property(when combined with runtime adjustment) |
Summary checklist
- RUID는 resource search/avatar reference documentobtain with.
- DefaultPlayer/Player →
./Global/*.model의Valuesor base model definition. - Map entity →
./map/*.mapthe corresponding entity of@components. - Longcoat / two-handed weapon / shield·secondary follow the exclusivity rules.
- **
UseCustomEquipOnly** explicitly state whether to “ignore the account's default costume.” - After saving,
msw-maker-mcp→refreshcall.