MSW 아바타 (코스튬 · 애니메이션)

아바타는 두 축으로 관리한다.

코스튬(외형):
```
MOD.Core.CostumeManagerComponent
```
— 어떤 장비를 착용하는가(17슬롯).
애니메이션(동작):
```
AvatarStateAnimationComponent
```
+
```
AvatarRendererComponent
```
— 어떤 상태 클립을 재생하는가(기본 14상태 + 커스텀 액션).

예전 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를 병행해 확보한다.

아바타 애니메이션 — 전체 구조

아바타 애니메이션은 3계층 파이프라인으로 흐른다. 한 계층만 보고 작업하면 다른 계층이 덮어써서 의도와 다른 동작이 나온다.

[1] 입력 / 게임 로직
       │  PlayerControllerComponent · 스크립트
       ▼
[2] StateComponent       ──── StateChangeEvent ────▶ AvatarStateAnimationComponent
       (ex. "ATTACK")            (CurrentStateName)        (StateToAvatarBodyActionSheet
                                                            또는 ActionSheet 룩업)
                                                                 │
                                                                 ▼
[3] AvatarRendererComponent ◀── BodyActionStateChange / ActionStateChanged ── 바디 엔티티
       (실제 스프라이트 재생)

핵심 구분:

용어	형식	예시
State 키	대문자 영문	`IDLE` , `MOVE` , `ATTACK` , `HIT` , `CROUCH` , `FALL` , `JUMP` , `CLIMB` , `LADDER` , `DEAD` , `SIT` , `ATTACK_WAIT`
AvatarBodyActionStateName (Value 쪽)	소문자 영문	`stand` , `walk` , `attack` , `hit` , `crouch` , `fall` , `rope` , `ladder` , `dead` , `sit` , `alert` , `fly` , `blink` , `heal`
MapleAvatarBodyActionState (enum)	Pascal case	`Stand` , `Walk` , `Attack` , `Hit` , `Crouch` , `Fall` , `Sit` , `Rope` , `Ladder` , `Dead` , `Blink` , `Fly` , `Heal` , `Alert` , `Invalid`
CoreActionName/PartsActionName (실제 스프라이트 액션 ID)	소문자+숫자	`stand1` , `walk1` , `swingO1` , `shoot1` , `prone` , `jump` , `alert` 등

흔한 혼동: "attack"은 State 가 아니다. State는 대문자
ATTACK
, 매핑 Value는 소문자
attack
(= MapleAvatarBodyActionState.Attack), 그리고 그 Value가 다시 무기에 따라
swingO1
/
shoot1
같은 스프라이트 액션 ID로 풀린다.

AvatarStateAnimationComponent — 상태↔동작 매핑

MOD.Core.AvatarStateAnimationComponent

는 두 시스템을 모두 갖고 있다.

프로퍼티 사용 조건 형식 비고

프로퍼티	사용 조건	형식	비고
`IsLegacy`	두 시스템 선택 스위치	`boolean` (기본 `false` )	`true` 이면 ActionSheet, `false` 이면 StateToAvatarBodyActionSheet 사용
`ActionSheet`	`IsLegacy = true` (구)	`SyncDictionary<string, string>`	`"ATTACK"` → `"attack"` 처럼 State→AnimationKey
`StateToAvatarBodyActionSheet`	`IsLegacy = false` (신, 기본)	`SyncDictionary<string, AvatarBodyActionElement>`	`"ATTACK"` → `{AvatarBodyActionStateName="attack", PlayRate=1.33}`

IsLegacy

두 시스템 선택 스위치

boolean

(기본

false

)

true

이면 ActionSheet,

false

이면 StateToAvatarBodyActionSheet 사용

ActionSheet

IsLegacy = true

(구)

SyncDictionary<string, string>

"ATTACK"

→

"attack"

처럼 State→AnimationKey

StateToAvatarBodyActionSheet

IsLegacy = false

(신, 기본)

SyncDictionary<string, AvatarBodyActionElement>

"ATTACK"

→

{AvatarBodyActionStateName="attack", PlayRate=1.33}

StateToAvatarBodyActionSheet

기본 매핑 (IsLegacy=false 기본 11개 키)

Key (State)	AvatarBodyActionStateName	PlayRate	트리거 조건(PlayerControllerComponent 동반 시)
`IDLE`	`stand`	1.0	입력 없음
`MOVE`	`walk`	1.68	좌/우 이동
`ATTACK`	`attack`	1.33	Left Ctrl (Attack 액션)
`HIT`	`hit`	1.0	HitComponent 피격 처리
`CROUCH`	`crouch`	1.0	아래 방향키
`FALL`	`fall`	1.0	공중에서 낙하
`JUMP`	`fall`	1.0	Space (Jump 액션)
`CLIMB`	`rope`	1.0	로프 진입
`LADDER`	`ladder`	1.0	사다리 진입
`DEAD`	`dead`	1.0	사망
`SIT`	`sit`	1.0	C (Sit 액션)

State 키는 대문자, AvatarBodyActionStateName 값은 소문자라는 점에 주의.

MapleAvatarBodyActionState

→ 실제 액션 ID 디폴트 변환표

AvatarBodyActionStateName

문자열 (

"attack"

"stand"

등)은 enum

MapleAvatarBodyActionState

로 캐스팅되고, 엔진은 이를 다음 기본값으로 풀어

ActionStateChangedEvent

를 합성한다.

MapleAvatarBodyActionState	CoreActionName	PartsActionName	PlayRate	PlayType
Stand	`stand1` / `stand2`	동일	1	ZigzagLoop
Walk	`walk1` / `walk2`	동일	1	Loop
Attack	`alert` (무기 미장착 기본)	`alert`	1	Loop
Crouch	`prone`	`prone`	1	Loop
Fall	`jump`	`jump`	1	Loop
Sit	`sit`	`sit`	1	Loop
Rope	`rope`	`rope`	1	Loop
Ladder	`ladder`	`ladder`	1	Loop
Dead	`dead`	`stand1`	1	Loop
Blink	`blink`	`blink`	1	Loop
Fly	`fly`	`fly`	1	Loop
Hit	`alert`	`alert`	1	ZigzagLoop
Alert	`alert`	`alert`	1	ZigzagLoop
Heal	`heal`	`heal`	1	Loop

무기를 장착하면
Attack
은 무기 종류에 맞는 스프라이트 액션 ID로 자동 치환된다 (다음 절 표 참조). 즉 한손검을 쥐면 칼 휘두르기, 활을 쥐면 활 쏘기 모션이 나온다.

무기별

attack

풀이 — 스프라이트 액션 ID 후보군

ATTACK

상태가 트리거되면 엔진이 장착 무기(MapleAvatarItemCategory)를 보고 다음 ID 중 하나로 액션을 재생한다.

무기 분류	사용되는 CoreActionName/PartsActionName 후보
한손검/단검 ( `OneHandedWeapon` )	`swingO1` , `swingO2` , `swingO3` , `stabO1` , `stabO2`
두손검/해머 ( `TwoHandedWeapon` )	`swingT1` , `swingT2` , `swingT3` , `stabT1` , `stabT2`
활 ( `TwoHandedWeapon` Bow 계열)	`swingT1` , `swingT3` , `shoot1`
스태프/완드	`swingO1` , `swingO2` , `swingO3`
무기 없음 (기본 body)	별도 attack 클립 없음 → `alert` 등으로 표시됨

같은 분류라도 아이템 메타에 따라 사용되는 액션 ID 집합이 다를 수 있다. 위 표는 SDK 가이드(
_ActionNameLogic
)가 사용하는 대표 후보군.

PlayerControllerComponent와 자동 상태 추가

플레이어 엔티티에

MOD.Core.PlayerControllerComponent

가 붙어 있으면

StateComponent

에 다음 State가 자동으로 추가되고 키 입력에 따라 자동 전이된다.

MOVE

CLIMB

LADDER

CROUCH

JUMP

FALL

ATTACK

ATTACK_WAIT

SIT

따라서 DefaultPlayer가 Ctrl을 누르면 자동으로 ATTACK 상태가 되고, 위 매핑에 따라 attack 바디 동작(=무기별 칼/활/지팡이 휘두르기)이 자동 재생된다. 스크립트로 별도 처리를 안 해도 칼은 휘둘러진다.

자동 재생 ↔ 수동 ActionStateChangedEvent 충돌 (★ 자주 만나는 함정)

증상: 스크립트에서

ActionStateChangedEvent

로

shoot1

같은 커스텀 액션을 보내도, 여전히 칼 휘두르기(또는 무기 기본 attack) 가 나오거나 한 프레임만 스치고 곧 덮인다.

원인:

ATTACK

상태가 활성인 동안

AvatarStateAnimationComponent

가 매핑된

attack

바디 동작을 지속적으로 보낸다. 우리가 보낸 1회성 이벤트는 즉시 덮인다.

해결 전략

전략	방법	언제 쓰나
A. 매핑 제거	`asac:RemoveActionSheet("ATTACK")` 로 해당 키를 지운다. 이후 `ActionStateChangedEvent` 로 직접 액션 재생.	공격 모션을 완전히 커스텀으로 대체할 때 (활 쏘기, 마법 시전 등)
B. 매핑 변경	`asac:SetActionSheet("ATTACK", "<Body Action 이름>")` 또는 `StateToAvatarBodyActionSheet["ATTACK"]` 을 다른 `MapleAvatarBodyActionState` 로 변경.	다른 내장 상태 애니메이션으로 바꾸고 싶을 때 (예: ATTACK→heal)
C. 강제 리셋	`BodyActionStateChangeEvent` 를 `needResetAction=true` 로 보낸다.	같은 상태를 재시작하고 싶을 때
D. 무기 교체	`CostumeManagerComponent` 의 무기 슬롯을 활 RUID로 바꾼다.	단순히 attack 모션의 무기 종류만 바꾸고 싶을 때 (가장 직관적)

전략 A 예시 — 칼 휘두르기 끄고 활 쏘기로 대체

lua

@Component
script PlayerAttack extends AttackComponent

	@HideFromInspector
	property any Shape = nil

	@ExecSpace("ServerOnly")
	method void OnBeginPlay()
		self.Shape = BoxShape(Vector2.zero, Vector2.one, 0)

		-- 엔진이 ATTACK 상태에서 자동 재생하던 attack(=칼 휘두르기) 매핑을 제거
		local asac = self.Entity.AvatarStateAnimationComponent
		if isvalid(asac) then
			asac:RemoveActionSheet("ATTACK")
		end
	end

	@ExecSpace("ServerOnly")
	method void AttackNormal()
		-- ... 데미지 판정 ...
		self:PlayShootAnimation()
	end

	@ExecSpace("Client")
	method void PlayShootAnimation()
		local body = self.Entity.AvatarRendererComponent:GetBodyEntity()
		if isvalid(body) == false then return end

		local event = ActionStateChangedEvent()
		event.CoreActionName = "shoot1"
		event.PartsActionName = "shoot1"
		event.PlayType = SpriteAnimClipPlayType.Onetime
		body:SendEvent(event)
	end

	@ExecSpace("ServerOnly")
	@EventSender("Self")
	handler HandlePlayerActionEvent(PlayerActionEvent event)
		if event.ActionName == "Attack" then
			self:AttackNormal()
		end
	end
end

RemoveActionSheet
/
SetActionSheet
는 서버에서 호출해야 동기화된다.
StateToAvatarBodyActionSheet
는
@Sync
프로퍼티이기 때문이다.

전략 D 예시 — CostumeManagerComponent로 활 장착

./Global/DefaultPlayer.model

의

Values

에 활 RUID를 추가하면, 매핑은 그대로 두어도 엔진이 ATTACK 상태에서

shoot1

모션을 자동으로 고른다.

json

{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "CustomTwoHandedWeaponEquip",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": "<bow RUID — msw-search 로 확보>"
},
{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "UseCustomEquipOnly",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": true
}

14상태 vs 커스텀 액션 — 무엇을 직접 발사해야 하나

AvatarStateAnimationComponent

이/

MapleAvatarBodyActionState

가 이미 알고 있는 14개 바디 동작과, 그 외의 임의 스프라이트 액션 ID(예:

swingO2

shoot1

dance

cast1

)는 처리 경로가 다르다.

엔진이 자동 처리하는 14개 바디 동작 (= MapleAvatarBodyActionState 멤버)

StateToAvatarBodyActionSheet

ActionSheet

의 Value로 쓸 수 있는 이름. State에 매핑만 해두면 자동 재생된다.

바디 동작 이름	enum	의미
`stand`	Stand	대기
`walk`	Walk	이동
`attack`	Attack	공격(무기에 따라 sprite ID 자동 결정)
`hit`	Hit	피격
`crouch`	Crouch	웅크리기
`fall`	Fall	낙하
`rope`	Rope	로프 잡기
`ladder`	Ladder	사다리
`dead`	Dead	사망
`sit`	Sit	앉기
`heal`	Heal	회복
`alert`	Alert	경계
`fly`	Fly	비행
`blink`	Blink	눈 깜박임

그 외 커스텀 동작 —

ActionStateChangedEvent

로 직접 재생

14개 enum 외의 임의 스프라이트 액션 ID(예:

shoot1

swingO2

cast1

throw1

dance

cheer

등)는 다음 절차로 재생한다.

재생 파이프라인

엔티티의
```
AvatarRendererComponent
```
에서 GetBodyEntity()
로 아바타 바디 엔티티를 얻는다. 애니메이션 이벤트는 아바타 본체가 아니라 바디 엔티티에 보낸다.
ActionStateChangedEvent
를 생성하고 필드를 채운다.
```
body:SendEvent(event)
```
로 바디 엔티티에 전송한다.
애니메이션 재생은 각 클라이언트에서 보이기만 하면 되므로 보통 @ExecSpace("Client")
로 한정한다. 게임 로직(데미지, 투사체 스폰 등)은
```
ServerOnly
```
쪽에서 처리한다.

ActionStateChangedEvent
주요 필드 (생성자:

ActionStateChangedEvent(coreActionName, partsActionName, playRate=1, playType=Loop, startFrameIndex=0, endFrameIndex=2147483647)

)

필드	타입	기본값	설명
`CoreActionName`	string	`""`	코어 파츠(바디)에서 재생할 애니메이션 ID. 필수 (예: `"shoot1"` , `"swingO1"` )
`PartsActionName`	string	`""`	부위 파츠에서 재생할 애니메이션 ID. 필수 — 보통 `CoreActionName` 과 같은 값
`PlayRate`	float	`1`	재생 속도 배율 ( `1.0` = 원속도, `1.5` = 1.5배속)
`PlayType`	`SpriteAnimClipPlayType`	`Loop`	`Onetime` / `Loop` / `ZigzagLoop` . 1회성 액션은 `Onetime`
`StartFrameIndex`	int32	`0`	시작 프레임 (음수면 0으로 보정)
`EndFrameIndex`	int32	`2147483647`	끝 프레임 (총 프레임 초과 시 자동 보정)

SpriteAnimClipPlayType

값	의미
`Onetime`	1회 재생 후 정지
`Loop`	0→끝 반복
`ZigzagLoop`	0→끝→0 왕복 반복

BodyActionStateChangeEvent

— 14개 내장 상태 고수준 이벤트

MapleAvatarBodyActionState

enum을 직접 지정해 변경한다. 무기별 액션 ID를 일일이 외울 필요가 없고, 같은 상태를 다시 재생하고 싶을 때

needResetAction=true

로 강제 리셋이 가능하다는 장점이 있다.

SendEvent

대상은

ActionStateChangedEvent

처럼 바디 엔티티가 아니라 아바타 루트 엔티티(
self.Entity
) 이다.

lua

local event = BodyActionStateChangeEvent()
event.ActionState = MapleAvatarBodyActionState.Fly
event.needResetAction = true
event.startFrameIndex = 1
event.endFrameIndex = 2
self.Entity:SendEvent(event)
-- 내부적으로 ActionStateChangedEvent("fly", "fly", 1, Loop, 1, 2)로 변환되어 전달

필드	설명
`ActionState`	`MapleAvatarBodyActionState` enum (Stand/Walk/Attack/Hit/...)
`needResetAction`	`true` 이면 같은 상태가 이미 재생 중이어도 처음부터 강제 재생
`playRate` / `startFrameIndex` / `endFrameIndex`	`ActionStateChangedEvent` 와 동일

선택 기준

임의 스프라이트 액션 ID(
```
shoot1
```
,
```
swingO2
```
,
```
dance
```
등) →
```
ActionStateChangedEvent
```
(바디 엔티티에 전송)
enum에 있는 14개 상태(Stand/Walk/Attack/...) →
```
BodyActionStateChangeEvent
```
(루트 엔티티에 전송)

예시 — 화살 발사(

shoot

) 애니메이션 재생

서버에서 공격 입력을 받으면 투사체를 스폰하고, 클라이언트에서

shoot1

액션을 재생하는 전형적인 패턴이다.

lua

@Component
script PlayerAttack extends Component

    property string ArrowModelId = "model://bc9f9d0e-2b5d-4b3b-a115-d857f85e9145"

    @HideFromInspector
    property integer ArrowCount = 0

    @ExecSpace("ServerOnly")
    method void FireArrow()
        if self.ArrowModelId == nil or self.ArrowModelId == "" then
            log_warning("PlayerAttack: ArrowModelId is not set")
            return
        end

        local playerController = self.Entity.PlayerControllerComponent
        local transform = self.Entity.TransformComponent
        if isvalid(playerController) == false or isvalid(transform) == false then
            return
        end

        local dirX = playerController.LookDirectionX
        if dirX == 0 then dirX = 1 end

        local worldPos = transform.WorldPosition
        local spawnPos = Vector3(worldPos.x + 0.35 * dirX, worldPos.y + 0.35, worldPos.z)

        self.ArrowCount += 1
        local arrowName = "PlayerArrow_" .. tostring(self.ArrowCount)

        local parent = self.Entity.CurrentMap
        if isvalid(parent) == false then
            parent = self.Entity.Parent
        end

        local arrow = _SpawnService:SpawnByModelId(self.ArrowModelId, arrowName, spawnPos, parent)
        if isvalid(arrow) == false then
            log_warning("PlayerAttack: failed to spawn arrow")
            return
        end

        local arrowProj = arrow.ArrowProjectile
        if isvalid(arrowProj) then
            arrowProj:Fire(Vector2(dirX, 0))
        end

        self:PlayShootAnimation()
    end

    @ExecSpace("Client")
    method void PlayShootAnimation()
        local avatarRenderer = self.Entity.AvatarRendererComponent
        if isvalid(avatarRenderer) == false then
            return
        end
        local body = avatarRenderer:GetBodyEntity()
        if isvalid(body) == false then
            return
        end

        local event = ActionStateChangedEvent()
        event.CoreActionName = "shoot1"
        event.PartsActionName = "shoot1"
        event.PlayRate = 1.5
        event.PlayType = SpriteAnimClipPlayType.Onetime
        body:SendEvent(event)
    end

    @ExecSpace("ServerOnly")
    @EventSender("Self")
    handler HandlePlayerActionEvent(PlayerActionEvent event)
        local ActionName = event.ActionName

        if ActionName == "Attack" then
            self:FireArrow()
        end
    end

end

의사결정 흐름

재생하려는 동작이 기본 14상태(
```
stand
```
,
```
walk
```
,
```
attack
```
,
```
hit
```
,
```
crouch
```
,
```
fall
```
,
```
rope
```
,
```
ladder
```
,
```
dead
```
,
```
sit
```
,
```
heal
```
,
```
alert
```
,
```
fly
```
,
```
blink
```
) 중 하나인가?
- YES →
```
AvatarStateAnimationComponent
```
  의 해당 슬롯에 클립을 지정만 하면 된다. 스크립트 불필요.
- NO → 아래로.

커스텀 액션(예:

shoot1

cast1

dance

)은 ActionStateChangedEvent
를 만들어

AvatarRendererComponent:GetBodyEntity()

가 반환한 바디 엔티티에

SendEvent

로 보낸다.

입력 처리·데미지 판정은 서버(
```
ServerOnly
```
)에서, 애니메이션 재생은 클라이언트(
Client
) 에서 나누어 실행한다.

자주 발생하는 실수

State 키와 AvatarBodyActionStateName(=enum)을 혼동. State 키는 대문자(
```
ATTACK
```
), 매핑 Value는 소문자(
```
attack
```
).
```
StateToAvatarBodyActionSheet
```
의 Key/Value를 뒤집어 넣으면 매핑이 작동하지 않는다.
자동 재생을 끄지 않고 ActionStateChangedEvent만 보내는 경우. Ctrl 입력 시
```
ATTACK
```
상태가 자동 활성화되어 매핑된 attack 바디 동작이 우리 이벤트를 즉시 덮는다. 커스텀 공격 모션을 쓰려면 반드시
```
RemoveActionSheet("ATTACK")
```
또는
```
SetActionSheet("ATTACK", "<원하는 동작>")
```
으로 매핑을 정리해야 한다.
ActionStateChangedEvent
의 SendEvent 대상: 반드시
```
AvatarRendererComponent:GetBodyEntity()
```
가 반환한 바디 엔티티.
```
self.Entity
```
(아바타 루트)나 컴포넌트에 보내면 재생되지 않는다. (반대로
```
BodyActionStateChangeEvent
```
는 루트 엔티티에 보낸다.)
AvatarStateAnimationComponent
에 임의 상태명을 넣는 시도. 14개 enum(
```
MapleAvatarBodyActionState
```
) 외 이름(
```
shoot
```
,
```
cast
```
,
```
dance
```
)을 Value로 넣으면 무시된다. 임의 ID는
```
ActionStateChangedEvent
```
경로로만.
PartsActionName
빠뜨리기.
```
CoreActionName
```
만 채우면 부위(무기·모자·망토 등) 애니메이션이 풀리지 않아 상체만 동작하고 무기는 멈춘 채 보일 수 있다. 보통
```
CoreActionName
```
과 같은 값을 사용.
PlayType
미지정. 기본값이
```
Loop
```
이라서 1회성 액션이 무한 반복된다. 1회성은 명시적으로
```
SpriteAnimClipPlayType.Onetime
```
.
RemoveActionSheet
/
SetActionSheet
를 클라이언트에서 호출.
```
StateToAvatarBodyActionSheet
```
는
```
@Sync
```
동기화 프로퍼티이므로 서버에서 호출해야 모든 클라이언트에 반영된다.
서버/클라이언트 실행 공간 분리 누락. 게임 로직(데미지·투사체) =
```
ServerOnly
```
, 애니메이션 재생 =
```
Client
```
. 두 경로를 한 곳에 몰아넣으면 클라마다 중복 재생되거나 시각 누락이 생긴다.
무기를 안 끼우고 활 모션만 기대.
```
shoot1
```
액션을 쏘면 바디는 활 자세가 되지만, 활 RUID가
CustomTwoHandedWeaponEquip
에 없으면 손에 활이 그려지지 않는다. 시각적으로 자연스러우려면 모션과 무기를 함께 세팅한다.

스킬	용도
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
호출.

애니메이션

State 키(대문자)와 바디 동작 이름(소문자) 구분.

StateToAvatarBodyActionSheet["ATTACK"] = AvatarBodyActionElement("attack", 1.33)

형태.

원하는 동작이 enum 14개 바디 동작(
```
stand
```
·
```
walk
```
·
```
attack
```
·
```
hit
```
·
```
crouch
```
·
```
fall
```
·
```
rope
```
·
```
ladder
```
·
```
dead
```
·
```
sit
```
·
```
heal
```
·
```
alert
```
·
```
fly
```
·
```
blink
```
) 에 포함되면 매핑만 정의하고 끝.

그 외 액션 ID(

shoot1

swingT3

dance

등)는 ActionStateChangedEvent
생성 →

AvatarRendererComponent:GetBodyEntity()

에 SendEvent
. enum 안의 상태 재시작은 BodyActionStateChangeEvent
+ 루트 엔티티.

CoreActionName

PartsActionName

PlayRate

PlayType

네 필드를 채우고, 1회성 액션은 SpriteAnimClipPlayType.Onetime
.

자동 상태 전이와 충돌하는지 확인. PlayerControllerComponent가 붙은 엔티티는 입력 시
```
MOVE/ATTACK/JUMP/...
```
가 자동 발화되므로, 커스텀 공격을 쓰려면 충돌 키를 RemoveActionSheet
또는 SetActionSheet
로 정리한다(서버에서 호출).
게임 로직은
```
@ExecSpace("ServerOnly")
```
, 애니메이션 재생은 @ExecSpace("Client")
로 분리한다.
공격 모션의 무기 종류만 바꾸는 것이 목적이라면, 가장 단순한 방법은 CostumeManagerComponent
의 무기 슬롯 RUID 교체 (전략 D).

msw-avatar

NPX Install

Tags

SKILL.md Content

MSW 아바타 (코스튬 · 애니메이션)

작업 대상별 편집 위치

변경 반영: MCP
`refresh`

RUID(리소스 고유 ID)

CostumeManagerComponent 개요

기타 동기화 프로퍼티

17 슬롯 ↔ 프로퍼티 ↔ MapleAvatarItemCategory

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

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

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

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

UseCustomEquipOnly 예시

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

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

아바타 리소스 검색 참고

아바타 애니메이션 — 전체 구조

AvatarStateAnimationComponent — 상태↔동작 매핑

`StateToAvatarBodyActionSheet`
기본 매핑 (IsLegacy=false 기본 11개 키)

`MapleAvatarBodyActionState`
→ 실제 액션 ID 디폴트 변환표

무기별
`attack`
풀이 — 스프라이트 액션 ID 후보군

PlayerControllerComponent와 자동 상태 추가

자동 재생 ↔ 수동 ActionStateChangedEvent 충돌 (★ 자주 만나는 함정)

해결 전략

전략 A 예시 — 칼 휘두르기 끄고 활 쏘기로 대체

전략 D 예시 — CostumeManagerComponent로 활 장착

14상태 vs 커스텀 액션 — 무엇을 직접 발사해야 하나

엔진이 자동 처리하는 14개 바디 동작 (= MapleAvatarBodyActionState 멤버)

그 외 커스텀 동작 —
`ActionStateChangedEvent`
로 직접 재생

`BodyActionStateChangeEvent`
— 14개 내장 상태 고수준 이벤트

예시 — 화살 발사(
`shoot`
) 애니메이션 재생

의사결정 흐름

자주 발생하는 실수

관련 스킬

요약 체크리스트

코스튬

애니메이션

msw-avatar

NPX Install

Tags

SKILL.md Content

MSW 아바타 (코스튬 · 애니메이션)

작업 대상별 편집 위치

변경 반영: MCP refresh

RUID(리소스 고유 ID)

CostumeManagerComponent 개요

기타 동기화 프로퍼티

17 슬롯 ↔ 프로퍼티 ↔ MapleAvatarItemCategory

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

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

DefaultPlayer.model — Values에 코스튬 넣기

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

UseCustomEquipOnly 예시

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

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

아바타 리소스 검색 참고

아바타 애니메이션 — 전체 구조

AvatarStateAnimationComponent — 상태↔동작 매핑

StateToAvatarBodyActionSheet 기본 매핑 (IsLegacy=false 기본 11개 키)

MapleAvatarBodyActionState → 실제 액션 ID 디폴트 변환표

무기별 attack 풀이 — 스프라이트 액션 ID 후보군

PlayerControllerComponent와 자동 상태 추가

자동 재생 ↔ 수동 ActionStateChangedEvent 충돌 (★ 자주 만나는 함정)

해결 전략

전략 A 예시 — 칼 휘두르기 끄고 활 쏘기로 대체

전략 D 예시 — CostumeManagerComponent로 활 장착

14상태 vs 커스텀 액션 — 무엇을 직접 발사해야 하나

엔진이 자동 처리하는 14개 바디 동작 (= MapleAvatarBodyActionState 멤버)

그 외 커스텀 동작 — ActionStateChangedEvent로 직접 재생

BodyActionStateChangeEvent — 14개 내장 상태 고수준 이벤트

예시 — 화살 발사(shoot) 애니메이션 재생

의사결정 흐름

자주 발생하는 실수

관련 스킬

요약 체크리스트

코스튬

애니메이션

변경 반영: MCP
`refresh`

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

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

`StateToAvatarBodyActionSheet`
기본 매핑 (IsLegacy=false 기본 11개 키)

`MapleAvatarBodyActionState`
→ 실제 액션 ID 디폴트 변환표

무기별
`attack`
풀이 — 스프라이트 액션 ID 후보군

그 외 커스텀 동작 —
`ActionStateChangedEvent`
로 직접 재생

`BodyActionStateChangeEvent`
— 14개 내장 상태 고수준 이벤트

예시 — 화살 발사(
`shoot`
) 애니메이션 재생