msw-defaultplayer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MSW DefaultPlayer

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

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

直接查询/修改DefaultPlayer模型文件，管理组件，设置移动/物理/HP/相机参数。

服装/Avatar装备请参考
msw-costume
技能。由于服装可应用于DefaultPlayer以外的所有实体，因此被单独拆分为独立技能。

DefaultPlayer 개요

DefaultPlayer 概述

DefaultPlayer란?

什么是DefaultPlayer？

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

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

是冒险岛世界制作工具（Maker）工作区中默认提供的玩家角色模型。

所有用户进入世界时，都会基于该模型生成玩家实体。
```
DefaultUserEnterLeaveLogic
```
的
```
PlayerUri
```
属性中指定了要使用的模型ID。

파일 위치 및 구조

文件位置及结构

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

파일	경로	역할
Player.model	`./Global/Player.model`	베이스 모델. Components 목록과 Properties 링크를 정의
DefaultPlayer.model	`./Global/DefaultPlayer.model`	Player를 상속( `BaseModelId: "player"` ). Values를 오버라이드

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

DefaultPlayer由两个.model文件组成：

文件	路径	作用
Player.model	`./Global/Player.model`	基础模型。定义组件列表与属性关联
DefaultPlayer.model	`./Global/DefaultPlayer.model`	继承自Player（ `BaseModelId: "player"` ）。重写参数值

重要提示：两个文件均位于
./Global/
文件夹下。自定义脚本文件需创建在
./RootDesk/MyDesk/
目录中。

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

DefaultPlayer通过直接编辑.model文件进行管理

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

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

DefaultPlayer通过直接编辑**

./Global/DefaultPlayer.model

**文件来管理。

修改属性值：在
```
DefaultPlayer.model
```
的
```
Values
```
数组中修改对应项的
```
Value
```
值
添加/移除组件：修改
```
DefaultPlayer.model
```
的
```
Components
```
数组
查看基础组件列表：参考
```
Player.model
```
的
```
Components
```
数组

파일 구조 상세

文件结构详细说明

Player.model (베이스)

Player.model（基础模型）

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

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

路径: ./Global/Player.model
EntryKey: model://player

```
Components
```
：玩家的全部基础组件列表（MOD.Core.*原生组件）
```
Properties
```
：定义模型属性到组件属性的关联（可在检查器中编辑的属性）
```
Values
```
：为空（默认值由引擎提供）

DefaultPlayer.model (오버라이드)

DefaultPlayer.model（重写模型）

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

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

路径: ./Global/DefaultPlayer.model
EntryKey: model://defaultplayer
BaseModelId: "player"

```
Components
```
：仅包含DefaultPlayer中新增的组件（例如：
```
script.PlayerHit
```
、
```
script.PlayerAttack
```
）
```
Values
```
：待重写的参数值数组

DefaultPlayer 기본 컴포넌트 목록

DefaultPlayer基础组件列表

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

컴포넌트	역할
TransformComponent	위치, 회전, 크기
MovementComponent	이동 속도, 점프력 제어
RigidbodyComponent	물리(중력, 발판), 메이플스토리 이동
KinematicbodyComponent	RectTileMap 상하좌우 이동
SideviewbodyComponent	SideViewRectTileMap 횡스크롤 이동
StateComponent	상태 머신 (Walk, Jump, Dead 등)
AvatarRendererComponent	아바타 렌더링, 색상, 감정표현
AvatarStateAnimationComponent	상태 → 아바타 애니메이션 연결
CostumeManagerComponent	장비/코스튬 관리 → 상세는 `msw-costume` 스킬 참조
CameraComponent	카메라 추적 설정
PlayerControllerComponent	입력-액션 매핑, 조건 처리
PlayerComponent	HP, 사망/부활, PVP, 맵 이동
ChatBalloonComponent	채팅 풍선
NameTagComponent	이름표
DamageSkinSettingComponent	데미지 스킨
DamageSkinSpawnerComponent	데미지 스킨 스폰
HitEffectSpawnerComponent	히트 이펙트 스폰
TriggerComponent	충돌 감지
InventoryComponent	인벤토리

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

컴포넌트	역할
script.PlayerHit	플레이어 피격 로직
script.PlayerAttack	플레이어 공격 로직

从Player.model继承的原生组件：

组件	作用
TransformComponent	位置、旋转、缩放
MovementComponent	控制移动速度、跳跃力
RigidbodyComponent	物理效果（重力、踏板）、冒险岛风格移动
KinematicbodyComponent	RectTileMap上下左右移动
SideviewbodyComponent	SideViewRectTileMap横版滚动移动
StateComponent	状态机（行走、跳跃、死亡等）
AvatarRendererComponent	Avatar渲染、颜色、表情
AvatarStateAnimationComponent	状态与Avatar动画关联
CostumeManagerComponent	装备/服装管理 → 详情参考 `msw-costume` 技能
CameraComponent	相机追踪设置
PlayerControllerComponent	输入-动作映射、条件处理
PlayerComponent	HP、死亡/复活、PVP、地图移动
ChatBalloonComponent	聊天气泡
NameTagComponent	名称标签
DamageSkinSettingComponent	伤害皮肤设置
DamageSkinSpawnerComponent	伤害皮肤生成
HitEffectSpawnerComponent	击中效果生成
TriggerComponent	碰撞检测
InventoryComponent	背包

DefaultPlayer.model中新增的脚本组件：

组件	作用
script.PlayerHit	玩家受击逻辑
script.PlayerAttack	玩家攻击逻辑

핵심 컴포넌트 빠른 참조

核心组件快速参考

컴포넌트	역할	핵심 프로퍼티/메서드
PlayerComponent	HP, 사망/부활, PVP, 맵 이동	`Hp` , `MaxHp` , `PVPMode` , `RespawnDuration` , `RespawnPosition` , `UserId` , `IsDead()` , `ProcessDead()` , `ProcessRevive()` , `MoveToMapPosition()`
PlayerControllerComponent	입력→액션 매핑, 조건 제어	`SetActionKey(key, actionName)` , `ActionAttack()` , `ActionJump()` , `LookDirectionX`
MovementComponent	이동 속도/점프 상위 인터페이스	`InputSpeed` (기본 1.0), `JumpForce` (기본 1), `Jump()` , `Stop()`
RigidbodyComponent	메이플 사이드뷰 물리 (중력/발판)	`Gravity` , `WalkAcceleration` , `WalkSpeed` , `AddForce()` , `IsOnGround()`
KinematicbodyComponent	RectTile 탑뷰 상하좌우 이동	(RectTile 맵 모드 전용)
SideviewbodyComponent	SideViewRectTile 사이드뷰	(SideViewRectTile 맵 모드 전용)
AvatarRendererComponent	아바타 렌더링/색상/감정표현	`SetColor()` , `SetAlpha()` , `PlayEmotion()` , `PlayRate`
StateComponent	상태 머신 (Walk/Jump/Dead)	`CurrentStateName` , `ChangeState()` , DeadEvent/ReviveEvent
NameTagComponent	이름표	`Name` , `FontSize` , `FontColor` , `NameTagRUID`
ChatBalloonComponent	채팅 풍선	`Message` , `ChatModeEnabled` , `ShowDuration`
CameraComponent	카메라 추적	`DeadZone` , `SoftZone` , `Damping` , `ScreenOffset`
TriggerComponent	충돌 감지	`BoxSize` , `Offset` , CollisionGroup

组件	作用	核心属性/方法
PlayerComponent	HP、死亡/复活、PVP、地图移动	`Hp` , `MaxHp` , `PVPMode` , `RespawnDuration` , `RespawnPosition` , `UserId` , `IsDead()` , `ProcessDead()` , `ProcessRevive()` , `MoveToMapPosition()`
PlayerControllerComponent	输入→动作映射、条件控制	`SetActionKey(key, actionName)` , `ActionAttack()` , `ActionJump()` , `LookDirectionX`
MovementComponent	移动速度/跳跃顶层接口	`InputSpeed` (默认1.0), `JumpForce` (默认1), `Jump()` , `Stop()`
RigidbodyComponent	冒险岛横版物理（重力/踏板）	`Gravity` , `WalkAcceleration` , `WalkSpeed` , `AddForce()` , `IsOnGround()`
KinematicbodyComponent	RectTile顶视角上下左右移动	（RectTile地图模式专用）
SideviewbodyComponent	SideViewRectTile横版视角	（SideViewRectTile地图模式专用）
AvatarRendererComponent	Avatar渲染/颜色/表情	`SetColor()` , `SetAlpha()` , `PlayEmotion()` , `PlayRate`
StateComponent	状态机（行走/跳跃/死亡）	`CurrentStateName` , `ChangeState()` , DeadEvent/ReviveEvent
NameTagComponent	名称标签	`Name` , `FontSize` , `FontColor` , `NameTagRUID`
ChatBalloonComponent	聊天气泡	`Message` , `ChatModeEnabled` , `ShowDuration`
CameraComponent	相机追踪	`DeadZone` , `SoftZone` , `Damping` , `ScreenOffset`
TriggerComponent	碰撞检测	`BoxSize` , `Offset` , CollisionGroup

DefaultPlayer Values 구조

DefaultPlayer Values结构

DefaultPlayer.model

의

Values

배열 항목 형식:

json

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

DefaultPlayer.model

的

Values

数组项格式如下：

json

{
  "TargetType": "组件名或null",
  "Name": "属性名",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "类型信息"
  },
  "Value": 值
}

TargetType 규칙

TargetType规则

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

```
null
```
：Player.model的Properties中定义的模型属性（通过Properties关联映射到实际组件属性）
```
"MOD.Core.组件名"
```
：直接重写指定原生组件的属性
```
"script.脚本名"
```
：自定义脚本组件的属性

모델 프로퍼티 (TargetType: null)

模型属性（TargetType: null）

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

모델 프로퍼티명	원본 컴포넌트.프로퍼티	설명	기본값
speed	MovementComponent.InputSpeed	이동 속도	1.0
jumpForce	MovementComponent.JumpForce	점프 높이	1.0
walkAcceleration	RigidbodyComponent.WalkAcceleration	가속/감속	1.0
gravity	RigidbodyComponent.Gravity	중력	1.0
cameraDeadZone	CameraComponent.DeadZone	카메라 데드존	`{x: 0.052, y: 0.08}`
cameraSoftZone	CameraComponent.SoftZone	카메라 소프트존	`{x: 0.268, y: 0.7}`
cameraDamping	CameraComponent.Damping	카메라 부드러운 추적	`{x: 2.5, y: 3.9}`
cameraScreen	CameraComponent.ScreenOffset	데드존 중심점	`{x: 0.5, y: 0.655}`
cameraDutch	CameraComponent.DutchAngle	카메라 회전	0.0
cameraOffset	CameraComponent.CameraOffset	카메라 위치 오프셋	`{x: 0.0, y: 0.0}`
nameTag	NameTagComponent.Name	이름표	`""`
damageSkinId	DamageSkinSettingComponent.DamageSkinId	데미지 스킨 타입	DataRef
damageDelayPerAttack	DamageSkinSettingComponent.DelayPerAttack	데미지 딜레이	0.05
triggerBodyBoxSize	TriggerComponent.BoxSize	충돌 감지 영역 크기	`{x: 0.66, y: 0.7}`
triggerBodyBoxOffset	TriggerComponent.BoxOffset	충돌 감지 영역 오프셋	`{x: 0.0, y: 0.35}`
triggerBodyColliderOffset	TriggerComponent.ColliderOffset	충돌체 오프셋	`{x: 0.0, y: 0.35}`
maxHp	PlayerComponent.MaxHp	최대 HP	1000

通过Player.model的Properties中定义的关联，映射到实际组件属性。

模型属性名	原组件.属性	说明	默认值
speed	MovementComponent.InputSpeed	移动速度	1.0
jumpForce	MovementComponent.JumpForce	跳跃高度	1.0
walkAcceleration	RigidbodyComponent.WalkAcceleration	加速/减速	1.0
gravity	RigidbodyComponent.Gravity	重力	1.0
cameraDeadZone	CameraComponent.DeadZone	相机死区	`{x: 0.052, y: 0.08}`
cameraSoftZone	CameraComponent.SoftZone	相机软区	`{x: 0.268, y: 0.7}`
cameraDamping	CameraComponent.Damping	相机平滑追踪	`{x: 2.5, y: 3.9}`
cameraScreen	CameraComponent.ScreenOffset	死区中心点	`{x: 0.5, y: 0.655}`
cameraDutch	CameraComponent.DutchAngle	相机旋转	0.0
cameraOffset	CameraComponent.CameraOffset	相机位置偏移	`{x: 0.0, y: 0.0}`
nameTag	NameTagComponent.Name	名称标签	`""`
damageSkinId	DamageSkinSettingComponent.DamageSkinId	伤害皮肤类型	DataRef
damageDelayPerAttack	DamageSkinSettingComponent.DelayPerAttack	伤害延迟	0.05
triggerBodyBoxSize	TriggerComponent.BoxSize	碰撞检测区域大小	`{x: 0.66, y: 0.7}`
triggerBodyBoxOffset	TriggerComponent.BoxOffset	碰撞检测区域偏移	`{x: 0.0, y: 0.35}`
triggerBodyColliderOffset	TriggerComponent.ColliderOffset	碰撞体偏移	`{x: 0.0, y: 0.35}`
maxHp	PlayerComponent.MaxHp	最大HP	1000

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

组件直接重写（TargetType: 指定组件）

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

TargetType	Name	설명	기본값
MOD.Core.CameraComponent	ZoomRatioMax	카메라 최대 줌 비율	500.0
MOD.Core.MovementComponent	JumpForce	점프력 (직접 오버라이드)	1.0
MOD.Core.MovementComponent	InputSpeed	이동 속도 (직접 오버라이드)	1.0
script.PlayerHit	CollisionGroup	피격 충돌 그룹	CollisionGroup ID
script.PlayerHit	BoxSize	피격 충돌 영역 크기	`{x: 0.45, y: 0.7}`
script.PlayerHit	ColliderOffset	피격 충돌 오프셋	`{x: 0.0, y: 0.35}`

不通过模型属性关联，直接重写组件属性的参数：

TargetType	Name	说明	默认值
MOD.Core.CameraComponent	ZoomRatioMax	相机最大缩放比例	500.0
MOD.Core.MovementComponent	JumpForce	跳跃力（直接重写）	1.0
MOD.Core.MovementComponent	InputSpeed	移动速度（直接重写）	1.0
script.PlayerHit	CollisionGroup	受击碰撞组	CollisionGroup ID
script.PlayerHit	BoxSize	受击碰撞区域大小	`{x: 0.45, y: 0.7}`
script.PlayerHit	ColliderOffset	受击碰撞体偏移	`{x: 0.0, y: 0.35}`

맵 모드별 이동 컴포넌트

按地图模式划分的移动组件

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

请参考
msw-general/references/platform.md §4
中的TileMapMode↔Body映射表。根据地图模式，RigidbodyComponent / KinematicbodyComponent / SideviewbodyComponent三者中会有一个被激活。

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

玩家识别方法（脚本参考）

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

```
entity.PlayerComponent ~= nil
```
→ 判断该实体是否为玩家
```
_UserService.LocalPlayer
```
→ 当前玩家实体（仅客户端可用）

_UserService:GetUserEntityByUserId(userId)

→ 指定用户的玩家实体

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

主要服务概述（脚本参考）

서비스	역할	핵심 API
_UserService	유저 관리, 입장/퇴장	`LocalPlayer` , `UserEntities` , `GetUserEntityByUserId()` , UserEnterEvent/UserLeaveEvent
_TeleportService	텔레포트/맵 이동	`TeleportToEntity()` , `TeleportToMapPosition()` , `WarpUserToWorldAsync()`
_CameraService	카메라 제어	`SwitchCameraTo()` , `ZoomTo()` , `ZoomReset()`
DefaultUserEnterLeaveLogic	유저 입장/퇴장 로직	`PlayerUri` (플레이어 모델 ID), `StartPoint` (시작 맵)

服务	作用	核心API
_UserService	用户管理、进入/退出	`LocalPlayer` , `UserEntities` , `GetUserEntityByUserId()` , UserEnterEvent/UserLeaveEvent
_TeleportService	传送/地图移动	`TeleportToEntity()` , `TeleportToMapPosition()` , `WarpUserToWorldAsync()`
_CameraService	相机控制	`SwitchCameraTo()` , `ZoomTo()` , `ZoomReset()`
DefaultUserEnterLeaveLogic	用户进入/退出逻辑	`PlayerUri` (玩家模型ID), `StartPoint` (起始地图)

DefaultPlayer 수정 방법

DefaultPlayer修改方法

속성값(Values) 수정

修改属性值(Values)

./Global/DefaultPlayer.model

파일을 열어

ContentProto.Json.Values

배열에서 해당 항목의

Value

를 수정한다.

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

Values

배열에서

Name

이

"speed"

인 항목을 찾아

Value

를 수정:

json

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

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

MovementComponent

의

InputSpeed

json

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

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

json

// 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 }

打开

./Global/DefaultPlayer.model

文件，修改

ContentProto.Json.Values

数组中对应项的

Value

值。

示例：将移动速度修改为2.0

在

Values

数组中找到

Name

为

"speed"

的项，修改其

Value

值：

json

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

或者在组件直接重写项中修改

MovementComponent

的

InputSpeed

：

json

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

数组中找到对应项修改：

json

// 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项

Values

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

주요 ValueType 패턴:

json

// 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

可通过在

Values

数组中新增项来重写默认值。需严格匹配ValueType格式。

主要ValueType格式:

json

// 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

배열에 항목 추가.

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

json

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

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

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

json

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

在

./Global/DefaultPlayer.model

的

ContentProto.Json.Components

数组中添加项。

添加自定义脚本组件:

json

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

自定义脚本（.mlua）必须创建在
./RootDesk/MyDesk/
目录下。需先编写脚本，再在Components数组中添加
"script.脚本名"
。

添加原生组件（示例：SpriteRendererComponent）:

json

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

컴포넌트 제거

移除组件

DefaultPlayer.model

의

Components

배열에서 해당 항목을 제거한다. 관련

Values

항목도 함께 제거해야 한다.

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

从

DefaultPlayer.model

的

Components

数组中移除对应项。同时需移除相关的

Values

项。

注意：从Player.model（基础模型）继承的组件不会出现在DefaultPlayer.model的Components中，若要移除基础组件，需直接修改Player.model。通常不建议移除基础组件。

DefaultPlayer 숨기기

隐藏DefaultPlayer

DefaultPlayer는 base model 상속 컴포넌트이므로 삭제 불가.

Enable=false

로 비활성화하는 것이 유일한 방법이다.

DefaultPlayer是继承自基础模型的组件，因此无法删除。唯一的隐藏方法是设置

Enable=false

使其失效。

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

组件保留/失效分类

컴포넌트	완전 숨기기	아바타만 숨기기	비고
TransformComponent	유지	유지	필수
PlayerComponent	유지	유지	필수 — 비활성화 시 입장 실패
StateComponent	유지	유지	비활성화 시 다른 컴포넌트 에러
MovementComponent	유지	유지	이동 필요 시 유지
CameraComponent	유지	유지	카메라 필요 시 유지
AvatarRendererComponent	비활성화	비활성화	핵심 — 이것만 꺼도 안 보임
AvatarStateAnimationComponent	비활성화	비활성화
CostumeManagerComponent	비활성화	비활성화
PlayerControllerComponent	비활성화	유지	이동 차단 여부에 따라
ChatBalloonComponent	비활성화	비활성화
NameTagComponent	비활성화	비활성화
DamageSkinSettingComponent	비활성화	비활성화
DamageSkinSpawnerComponent	비활성화	비활성화
HitComponent	비활성화	비활성화
HitEffectSpawnerComponent	비활성화	비활성화
TriggerComponent	비활성화	비활성화
InventoryComponent	비활성화	비활성화
RigidbodyComponent	비활성화	맵 모드 유지	MapleTile 맵일 때
SideviewbodyComponent	비활성화	맵 모드 유지	SideViewRectTile 맵일 때
KinematicbodyComponent	EnableShadow=false	EnableShadow=false	그림자만 제거

组件	完全隐藏	仅隐藏Avatar	备注
TransformComponent	保留	保留	必需
PlayerComponent	保留	保留	必需 — 失效会导致进入失败
StateComponent	保留	保留	失效会导致其他组件报错
MovementComponent	保留	保留	需要移动时保留
CameraComponent	保留	保留	需要相机时保留
AvatarRendererComponent	失效	失效	核心 — 仅关闭此项即可隐藏
AvatarStateAnimationComponent	失效	失效
CostumeManagerComponent	失效	失效
PlayerControllerComponent	失效	保留	根据是否需要禁止移动选择
ChatBalloonComponent	失效	失效
NameTagComponent	失效	失效
DamageSkinSettingComponent	失效	失效
DamageSkinSpawnerComponent	失效	失效
HitComponent	失效	失效
HitEffectSpawnerComponent	失效	失效
TriggerComponent	失效	失效
InventoryComponent	失效	失效
RigidbodyComponent	失效	根据地图模式保留	当使用MapleTile地图时
SideviewbodyComponent	失效	根据地图模式保留	当使用SideViewRectTile地图时
KinematicbodyComponent	EnableShadow=false	EnableShadow=false	仅移除阴影

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

文件编辑 — 在Values中添加Enable=false

./Global/DefaultPlayer.model

의

ContentProto.Json.Values

배열에 항목 추가. 기존에 없는 컴포넌트 Enable 항목은 새로 추가한다.

json

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

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

json

{
  "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 필수.

在

./Global/DefaultPlayer.model

的

ContentProto.Json.Values

数组中添加项。若组件无现成的Enable项，则需新增。

json

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

按照相同格式为每个需要失效的组件添加项。移除阴影的设置如下：

json

{
  "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 컴포넌트 확장 패턴

DefaultPlayer组件扩展模式

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

非Avatar玩家：禁用AvatarRendererComponent → 添加SpriteRendererComponent → 设置SpriteRUID。
碰撞设置：在TriggerComponent的Values中调整ColliderType、CollisionGroup。
生成位置：在地图（.map）文件的Special中放置SpawnLocation（复活位置）。

워크플로우

工作流程

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

修改玩家基础属性（移动速度、跳跃力、HP等）

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

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. 在./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. 파일 저장

1. 打开./Global/DefaultPlayer.model文件
2. 在Values中修改cameraDeadZone、cameraSoftZone、cameraDamping、cameraScreen、cameraDutch、cameraOffset
3. 保存文件

경계 및 주의사항

边界与注意事项

담당 영역

负责范围

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

查询/修改DefaultPlayer/Player模型文件（.model）
添加/移除组件（Components数组）
设置移动/物理/HP/相机参数（Values数组）

비담당 영역

非负责范围

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

服装/Avatar装备 → 参考
```
msw-costume
```
技能
UI编辑器 → 参考
```
./ui/
```
文件夹下的.ui文件（专属技能）
地图编辑 → 参考
```
./map/
```
文件夹下的.map文件（专属技能，包含NPC/怪物生成）
通用脚本/资源 → 参考各专属技能

제약

限制

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

注意Global/文件夹：DefaultPlayer.model和Player.model位于
```
./Global/
```
目录下。该文件夹为引擎默认模板专属，不建议创建新文件。
自定义脚本位置：新脚本文件必须创建在
```
./RootDesk/MyDesk/
```
目录下。
注意地图模式：根据地图模式（MapleTile/RectTile/SideViewRectTile），激活的移动组件会有所不同。
ValueType准确性：新增Values项时，需确保
```
ValueType
```
格式（尤其是程序集版本）与现有项一致。
Maker Refresh：添加/修改脚本后需执行Maker Refresh（自动生成.codeblock）。