msw-defaultplayer（MSW 默认播放器）

MSW DefaultPlayer

DefaultPlayer 모델 파일 직접 조회/수정, 컴포넌트 관리, 이동/물리/HP/카메라 설정.

코스튬/아바타 장비는 msw-costume 스킬을 참조. 코스튬은 DefaultPlayer뿐 아니라 모든 엔티티에 적용 가능하므로 별도 스킬로 분리되어 있다.

DefaultPlayer 개요

DefaultPlayer란?

메이플스토리 월드 메이커(Maker)의 워크스페이스에 기본 제공되는 플레이어 캐릭터 모델이다.

• 모든 유저가 월드에 접속하면 이 모델을 기반으로 플레이어 엔티티가 생성된다.
• DefaultUserEnterLeaveLogic의 PlayerUri 프로퍼티에 사용할 모델 ID가 지정된다.

파일 위치 및 구조

DefaultPlayer는 두 개의.model 파일로 구성된다:

중요: 두 파일 모두 ./Global/ 폴더에 위치한다. 커스텀 스크립트 파일은 ./RootDesk/MyDesk/에 생성한다.

DefaultPlayer는.model 파일로 직접 편집한다

DefaultPlayer는 ./Global/DefaultPlayer.model 파일을 직접 읽고 수정하여 관리한다.

• 속성값 변경: DefaultPlayer.model의 Values 배열에서 해당 항목의 Value를 수정
• 컴포넌트 추가/제거: DefaultPlayer.model의 Components 배열을 수정
• 베이스 컴포넌트 목록 확인: Player.model의 Components 배열 참조

파일 구조 상세

Player.model (베이스)

경로: ./Global/Player.model
EntryKey: model://player

• Components: 플레이어의 기본 컴포넌트 전체 목록 (MOD.Core.* 네이티브 컴포넌트)
• Properties: 모델 프로퍼티 → 컴포넌트 프로퍼티 링크 정의 (인스펙터에서 편집 가능한 프로퍼티)
• Values: 비어 있음 (기본값은 엔진이 제공)

DefaultPlayer.model (오버라이드)

경로: ./Global/DefaultPlayer.model
EntryKey: model://defaultplayer
BaseModelId: "player"

• Components: DefaultPlayer에 추가된 컴포넌트만 (예: script.PlayerHit, script.PlayerAttack)
• Values: 오버라이드할 설정값 배열

DefaultPlayer 기본 컴포넌트 목록

Player.model로부터 상속되는 네이티브 컴포넌트:

DefaultPlayer.model에서 추가된 스크립트 컴포넌트:

핵심 컴포넌트 빠른 참조

DefaultPlayer Values 구조

DefaultPlayer.model의 Values 배열 항목 형식:

{
  "TargetType": "컴포넌트명 또는 null",
  "Name": "프로퍼티명",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "타입 정보"
  },
  "Value": 값
}

TargetType 규칙

• null: Player.model의 Properties에 정의된 모델 프로퍼티 (Properties 링크를 통해 실제 컴포넌트 프로퍼티로 연결됨)
• "MOD.Core.컴포넌트명": 특정 네이티브 컴포넌트의 프로퍼티를 직접 오버라이드
• "script.스크립트명": 커스텀 스크립트 컴포넌트의 프로퍼티

모델 프로퍼티 (TargetType: null)

Player.model의 Properties에서 정의된 링크를 통해 실제 컴포넌트 프로퍼티로 매핑된다.

컴포넌트 직접 오버라이드 (TargetType: 특정 컴포넌트)

모델 프로퍼티 링크가 아닌, 컴포넌트 프로퍼티를 직접 오버라이드하는 값:

맵 모드별 이동 컴포넌트

TileMapMode↔Body 매핑 테이블은 msw-general/references/platform.md §4 참조. 맵 모드에 따라 RigidbodyComponent / KinematicbodyComponent / SideviewbodyComponent 중 하나가 활성화된다.

플레이어 식별 방법 (스크립트 참조)

• entity.PlayerComponent ~= nil → 해당 엔티티가 플레이어인지 확인
• _UserService.LocalPlayer → 나의 플레이어 엔티티 (클라이언트 전용)
• _UserService:GetUserEntityByUserId(userId) → 특정 유저의 플레이어 엔티티

주요 서비스 요약 (스크립트 참조)

DefaultPlayer 수정 방법

속성값(Values) 수정

./Global/DefaultPlayer.model 파일을 열어 ContentProto.Json.Values 배열에서 해당 항목의 Value를 수정한다.

예: 이동 속도를 2.0으로 변경

Values 배열에서 Name이 "speed"인 항목을 찾아 Value를 수정:

{
  "TargetType": null,
  "Name": "speed",
  "ValueType": { ... },
  "Value": 2.0
}

또는 컴포넌트 직접 오버라이드 항목에서 MovementComponent의 InputSpeed:

{
  "TargetType": "MOD.Core.MovementComponent",
  "Name": "InputSpeed",
  "ValueType": { ... },
  "Value": 2.0
}

참고: 모델 프로퍼티(TargetType: null, Name: "speed")와 컴포넌트 직접 오버라이드(TargetType: "MOD.Core.MovementComponent", Name: "InputSpeed")가 모두 존재할 수 있다. 양쪽을 일관되게 수정해야 한다.

예: 점프력 1.5 + HP 2000으로 변경

Values 배열에서 각각의 항목을 찾아 수정:

// jumpForce 모델 프로퍼티
{ "TargetType": null, "Name": "jumpForce", "Value": 1.5 }

// MovementComponent 직접 오버라이드
{ "TargetType": "MOD.Core.MovementComponent", "Name": "JumpForce", "Value": 1.5 }

// maxHp 모델 프로퍼티
{ "TargetType": null, "Name": "maxHp", "Value": 2000 }

새 Values 항목 추가

Values 배열에 새 항목을 추가하여 기본값을 오버라이드할 수 있다. ValueType 형식을 정확히 맞춰야 한다.

주요 ValueType 패턴:

// float (System.Single)
"ValueType": {
  "$type": "MODNativeType",
  "type": "System.Single, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
}

// int (System.Int64)
"ValueType": {
  "$type": "MODNativeType",
  "type": "System.Int64, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
}

// string
"ValueType": {
  "$type": "MODNativeType",
  "type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
}

// Vector2 (MODVector2)
"ValueType": {
  "$type": "MODNativeType",
  "type": "MOD.Core.MODVector2, MOD.Core, Version=1.11.0.0, Culture=neutral, PublicKeyToken=null"
}
// Value 형식: { "$type": "MOD.Core.MODVector2, MOD.Core", "x": 0.0, "y": 0.0 }

// DataRef (MODDataRef)
"ValueType": {
  "$type": "MODNativeType",
  "type": "MOD.Core.MODDataRef, MOD.Core, Version=1.11.0.0, Culture=neutral, PublicKeyToken=null"
}
// Value 형식: { "$type": "MOD.Core.MODDataRef, MOD.Core", "DataId": "hex..." }

// CollisionGroup
"ValueType": {
  "$type": "MODNativeType",
  "type": "MOD.Core.Physics.CollisionGroup, MOD.Core, Version=1.11.0.0, Culture=neutral, PublicKeyToken=null"
}
// Value 형식: { "$type": "MOD.Core.Physics.CollisionGroup, MOD.Core", "Id": "hex..." }

// boolean (System.Boolean) — Enable=false/true에 사용
"ValueType": {
  "$type": "MODNativeType",
  "type": "System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
}
// Value 형식: true 또는 false

컴포넌트 추가

./Global/DefaultPlayer.model의 ContentProto.Json.Components 배열에 항목 추가.

커스텀 스크립트 컴포넌트 추가:

"Components": [
  "script.PlayerHit",
  "script.PlayerAttack",
  "script.MyCustomComponent"
]

커스텀 스크립트(.mlua)는 반드시 ./RootDesk/MyDesk/에 생성해야 한다. 스크립트를 먼저 작성한 후 Components 배열에 "script.스크립트명"으로 추가한다.

네이티브 컴포넌트 추가 (예: SpriteRendererComponent):

"Components": [
  "script.PlayerHit",
  "script.PlayerAttack",
  "MOD.Core.SpriteRendererComponent"
]

컴포넌트 제거

DefaultPlayer.model의 Components 배열에서 해당 항목을 제거한다. 관련 Values 항목도 함께 제거해야 한다.

주의: Player.model(베이스)에서 상속된 컴포넌트는 DefaultPlayer.model의 Components에 없으므로, 베이스 컴포넌트를 제거하려면 Player.model 자체를 수정해야 한다. 일반적으로 베이스 컴포넌트 제거는 권장하지 않는다.

DefaultPlayer 숨기기

DefaultPlayer는 base model 상속 컴포넌트이므로 삭제 불가. Enable=false로 비활성화하는 것이 유일한 방법이다.

컴포넌트 유지/비활성화 분류

파일 편집 — Values에 Enable=false 추가

./Global/DefaultPlayer.model의 ContentProto.Json.Values 배열에 항목 추가. 기존에 없는 컴포넌트 Enable 항목은 새로 추가한다.

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

동일 패턴으로 비활성화할 컴포넌트마다 항목 추가. 그림자 제거는:

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

파일 저장 후 Maker Refresh 필수.

DefaultPlayer 컴포넌트 확장 패턴

• 비아바타 플레이어: AvatarRendererComponent 비활성화 → SpriteRendererComponent 추가 → SpriteRUID 설정.
• 충돌 설정: TriggerComponent의 Values에서 ColliderType, CollisionGroup 조정.
• SpawnLocation: 맵(.map) 파일에서 Special → SpawnLocation 배치 (부활 위치).

워크플로우

플레이어 기본 속성 수정 (이동 속도, 점프력, HP 등)

1. ./Global/DefaultPlayer.model 파일 읽기 → Values 배열 확인
2. 수정할 프로퍼티 항목을 찾아 Value 변경
3. 모델 프로퍼티(TargetType: null)와 컴포넌트 직접 오버라이드가 모두 있는 경우 양쪽 일관 수정
4. 파일 저장

플레이어에 커스텀 스크립트 추가

1. ./RootDesk/MyDesk/ 에 새 .mlua 스크립트 작성 (msw-scripting 스킬 참조)
2. ./Global/DefaultPlayer.model 의 Components 배열에 "script.스크립트명" 추가
3. 필요 시 Values 배열에 스크립트 프로퍼티 기본값 추가
4. Maker Refresh 요청 (.codeblock 자동 생성)

카메라 설정 변경

1. ./Global/DefaultPlayer.model 읽기
2. Values에서 cameraDeadZone, cameraSoftZone, cameraDamping, cameraScreen, cameraDutch, cameraOffset 수정
3. 파일 저장

경계 및 주의사항

담당 영역

• DefaultPlayer/Player 모델 파일(.model) 조회/수정
• 컴포넌트 추가/제거 (Components 배열)
• 이동/물리/HP/카메라 설정 (Values 배열)

비담당 영역

• 코스튬/아바타 장비 → msw-costume 스킬
• UI 에디터 → ./ui/ 폴더의.ui 파일 (전용 스킬)
• 맵 편집 → ./map/ 폴더의.map 파일 (전용 스킬, NPC/몬스터 스폰 포함)
• 일반 스크립트/리소스 → 각 전용 스킬

제약

1. Global/ 폴더 주의: DefaultPlayer.model과 Player.model은 ./Global/에 있다. 이 폴더는 엔진 기본 템플릿 전용이므로 신규 파일 생성은 권장하지 않는다.
2. 커스텀 스크립트 위치: 새 스크립트 파일은 반드시 ./RootDesk/MyDesk/에 생성한다.
3. 맵 모드 주의: 맵 모드(MapleTile/RectTile/SideViewRectTile)에 따라 활성 이동 컴포넌트가 다르다.
4. ValueType 정확성: Values 항목 추가 시 ValueType 형식(특히 어셈블리 버전)을 기존 항목과 일치시켜야 한다.
5. Maker Refresh: 스크립트 추가/수정 후에는 Maker Refresh가 필요하다 (.codeblock 자동 생성).