--- title: ZEPETO.Character.Controller slug: world-sdk-guide-kr/zepetocharactercontroller docTags: createdAt: 2026-09-04T06:56:37.640Z --- | 형식 | 설명 | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [ZepetoPlayers](./#zepetoplayers) | ZEPETO 플레이어와 ZEPETO 캐릭터를 모두 제어하기 위한 매니저 클래스입니다. | | [SpawnInfo](./#spawninfo) | ZEPETO 캐릭터의 스폰 위치를 나타냅니다. | | [ZepetoCharacter](./#zepetocharacter) | ZEPETO World에서 로드하고 제어할 수 있는 ZEPETO 캐릭터를 나타냅니다. | | [CameraData](./#cameradata) | `ZepetoCamera`의 초기 설정을 나타냅니다. | | [CharacterData](./#characterdata) | `ZepetoCharacter`의 초기 설정을 나타냅니다. | | [ControllerData](./#controllerdata) | `ZepetoPlayerControl`의 설정을 나타냅니다. | | [FloatingUIData](./#floatinguidata) | 캐릭터 관련 UI 설정을 관리하는 클래스입니다. | | [LocalPlayer](./#localplayer) | 이동, 코스튬 커스터마이징, ZEPETO 카메라 조작 등 로컬 플레이어의 동작을 관리하기 위한 클래스입니다. | | [ZepetoCamera](./#zepetocamera) | ZEPETO Character Controller에서 사용하도록 설계된 카메라 제어 클래스입니다. | | [ZepetoPlayer](./#zepetoplayer) | ZEPETO 플레이어를 나타냅니다. | | [ZepetoPlayerControl](./#zepetoplayercontrol) | ZEPETO 플레이어의 입력 제어를 관리합니다. | | [ZepetoCameraControl](./#zepetocameracontrol) | 카메라 이동과 줌의 입력 처리를 포함해 ZEPETO 환경의 카메라 조작을 관리합니다. | | [CharacterState](./#characterstate) | ZEPETO 캐릭터의 상태를 나타냅니다. | | [CharacterMoveState](./#charactermovestate) | ZEPETO 캐릭터의 세부 이동 상태를 나타냅니다. | | [CharacterJumpState](./#characterjumpstate) | ZEPETO 캐릭터의 세부 점프 상태를 나타냅니다. | | [CharacterLandingState](./#characterlandingstate) | ZEPETO 캐릭터의 세부 착지 상태를 나타냅니다. | | [KnowSockets](./#knowsockets) | 캐릭터의 알려진 부착 지점, 즉 소켓의 집합을 정의합니다. | | [MotionState](./#motionstate) | 캐릭터의 모션 상태와 설정을 관리하는 클래스입니다. | | [CharacterStateMachine](./#characterstatemachine) | ZEPETO 캐릭터의 캐릭터 상태와 Animator를 동기화하는 클래스입니다. | | [StateMachine](./#statemachine) | `StateMachine`은 `States`, `Transitions`, `Events`를 관리합니다. 지정된 조건과 경과 시간에 따라 상태를 갱신함으로써 객체의 다양한 상태를 정의하고 제어할 수 있습니다. | | [StateStatus](./#statestatus) | 상태 머신 내 상태가 가질 수 있는 스테이터스를 나타내며, 상태 생명 주기의 현재 단계를 보여줍니다. | | [CustomMotionData](./#custommotiondata) | 캐릭터 모션의 커스텀 설정을 나타냅니다. | | [CharacterShadow](./#charactershadow) | ZEPETO 캐릭터의 그림자를 관리하는 클래스입니다. | | [CameraState](./#camerastate) | `ZepetoCamera`의 상태를 나타냅니다. | | [ZepetoScreenStick](./#zepetoscreenstick) | ZEPETO 환경의 스틱 조작을 처리하기 위한 클래스입니다. | | [ZepetoScreenControl](./#zepetoscreencontrol) | ZEPETO 환경에서 UI 컨트롤을 만들기 위한 추상 클래스입니다. | | [ZepetoScreenButton](./#zepetoscreenbutton) | ZEPETO 환경의 버튼 조작을 처리하기 위한 클래스입니다. | | [ZepetoScreenTouchpad](./#zepetoscreentouchpad) | ZEPETO 환경의 터치패드 조작을 처리하기 위한 클래스입니다. | | [UIZepetoPlayerControl](./#uizepetoplayercontrol) | 로컬 플레이어의 캐릭터를 UI로 조작하는 기능을 제공하는 클래스입니다. | | [InputHelper](./#inputhelper) | 입력 처리를 돕기 위한 유틸리티 클래스입니다. | | [EventReceiver](./#eventreceiver) | ZEPETO World 내의 캐릭터 관련 이벤트나 일반 이벤트를 처리하는 클래스입니다. | | [TransitionBase](./#transitionbase) | 상태 머신에서 상태 간 전이를 정의하기 위한 기본 클래스입니다. | | [State](./#state) | 상태 머신 내의 상태를 나타냅니다. | | [Transition](./#transition) | 상태 머신에서 상태 간 전이를 정의하기 위한 제네릭 클래스입니다. | | [ZepetoCharacter.LoadingStatus](./#zepetocharacterloadingstatus) | ZEPETO 캐릭터의 로딩 상태입니다. | | [PlayerControlMode](./#playercontrolmode) | *enum* | ## ZepetoPlayers `class` ZEPETO 플레이어와 ZEPETO 캐릭터를 모두 제어하기 위한 매니저 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ----------------- | ----------------------------------- | ----------------------------- | | cameraData | [CameraData](./#cameradata) | `ZepetoCamera`의 설정입니다. | | characterData | [CharacterData](./#characterdata) | `ZepetoCharacter`의 설정입니다. | | controllerData | [ControllerData](./#controllerdata) | `ZepetoPlayerControl`의 설정입니다. | | floatingUIData | [FloatingUIData](./#floatinguidata) | 캐릭터 관련 UI 설정입니다. | | instance (static) | [ZepetoPlayers](./#zepetoplayers) | `ZepetoPlayers`의 싱글턴 인스턴스입니다. | | LocalPlayer | [LocalPlayer](./#localplayer) | 로컬 플레이어입니다. | | ZepetoCamera | [ZepetoCamera](./#zepetocamera) | ZEPETO 카메라입니다. | ### 이벤트 | 이름 | 형식 | 설명 | | ------------------ | -------------------- | -------------------------------- | | OnAddedLocalPlayer | `UnityEvent` | 로컬 플레이어 인스턴스가 생성될 때 발생하는 이벤트입니다. | | OnAddedPlayer | `UnityEvent` | 플레이어 인스턴스가 생성될 때 발생하는 이벤트입니다. | | OnRemovedPlayer | `UnityEvent` | 플레이어 인스턴스가 제거될 때 발생하는 이벤트입니다. | ### 메서드 ### add\_onInitialized `static add_onInitialized(value: Action) → void` `ZepetoPlayers`가 초기화될 때 호출되는 이벤트에 핸들러 함수를 추가합니다. | 매개변수 | 형식 | | ----- | -------- | | value | `Action` | ### remove\_onInitialized `static remove_onInitialized(value: Action) → void` `ZepetoPlayers`가 초기화될 때 호출되는 이벤트에서 핸들러 함수를 제거합니다. | 매개변수 | 형식 | | ----- | -------- | | value | `Action` | ### HasPlayer `HasPlayer(id: string) → boolean` 지정한 세션 ID에 연결된 플레이어 인스턴스가 존재하는지 확인합니다. | 매개변수 | 형식 | 설명 | | ---- | -------- | ----- | | id | `string` | 세션 ID | **반환값:** `boolean` ### GetPlayer `GetPlayer(id: string) → ZepetoPlayer` 지정한 세션 ID에 연결된 플레이어 인스턴스를 가져옵니다. | 매개변수 | 형식 | 설명 | | ---- | -------- | ----- | | id | `string` | 세션 ID | **반환값:** [ZepetoPlayer](./#zepetoplayer) — 지정한 ID에 연결된 플레이어 객체입니다. 해당 ID의 플레이어가 존재하지 않으면 `null`을 반환합니다. ### GetPlayerWithUserId `GetPlayerWithUserId(userId: string) → ZepetoPlayer` 지정한 사용자 ID에 연결된 플레이어 인스턴스를 가져옵니다. | 매개변수 | 형식 | 설명 | | ------ | -------- | ------ | | userId | `string` | 사용자 ID | **반환값:** [ZepetoPlayer](./#zepetoplayer) — 지정한 사용자 ID에 연결된 플레이어 객체입니다. ### RemovePlayer `RemovePlayer(id: string) → void` 지정한 세션 ID에 연결된 플레이어 인스턴스를 제거합니다. | 매개변수 | 형식 | 설명 | | ---- | -------- | ----- | | id | `string` | 세션 ID | ### DeformDefaultCostume `DeformDefaultCostume() → void` 모든 플레이어 캐릭터가 착용한 신체 변형 아이템을 제거합니다. 기본 체형으로 되돌리고 기본 ZEPETO 의상을 적용합니다. ### DeformDefaultProperties `DeformDefaultProperties() → void` 모든 플레이어 캐릭터가 착용한 신체 변형 아이템을 제거합니다. ## SpawnInfo `class` ZEPETO 캐릭터의 스폰 위치를 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | ---------------- | ------------------------- | ------------------------ | | Default (static) | [SpawnInfo](./#spawninfo) | 기본 스폰 위치입니다. | | position | `Vector3` | 스폰 시 ZEPETO 캐릭터의 위치입니다. | | rotation | `Quaternion` | 스폰 시 ZEPETO 캐릭터의 회전값입니다. | ## ZepetoCharacter `class` ZEPETO World에서 로드하고 제어할 수 있는 ZEPETO 캐릭터를 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | ------------------- | ------------------------------------------------- | ---------------------------------- | | additionalWalkSpeed | `number` | 추가 걷기 속도를 가져옵니다. | | additionalRunSpeed | `number` | 추가 달리기 속도를 가져옵니다. | | additionalJumpPower | `number` | 추가 점프력을 가져옵니다. | | constraintRotation | `boolean` | 캐릭터의 회전을 제한할지 여부를 결정합니다. | | ZepetoAnimator | `Animator` | ZEPETO 캐릭터의 Animator입니다. | | WalkSpeed | `number` | 기본 속도와 추가 속도를 합한 전체 걷기 속도를 가져옵니다. | | RunSpeed | `number` | 기본 속도와 추가 속도를 합한 전체 달리기 속도를 가져옵니다. | | JumpPower | `number` | 기본 점프력과 추가 점프력을 합한 전체 점프력을 가져옵니다. | | baseWalkSpeed | `number` | 기본 걷기 속도를 가져옵니다. | | baseRunSpeed | `number` | 기본 달리기 속도를 가져옵니다. | | baseJumpPower | `number` | 기본 점프력을 가져옵니다. | | tryMove | `boolean` | 캐릭터가 이동을 시도 중인지 여부를 나타냅니다. | | tryJump | `boolean` | 캐릭터가 점프를 시도 중인지 여부를 나타냅니다. | | tryDoubleJump | `boolean` | 캐릭터가 더블 점프를 시도 중인지 여부를 나타냅니다. | | motionState | [MotionState](./#motionstate) | 캐릭터의 모션 상태와 설정입니다. | | loadingStatus | [LoadingStatus](./#zepetocharacterloadingstatus) | 캐릭터의 로딩 상태입니다. | | Context | `ZepetoContext` | 캐릭터의 ZEPETO Context입니다. | | StateMachine | [CharacterStateMachine](./#characterstatemachine) | 캐릭터의 상태 머신입니다. | | CurrentState | [CharacterState](./#characterstate) | 상태 머신에 정의된 캐릭터의 현재 상태입니다. | | CurrentStateStatus | [StateStatus](./#statestatus) | 상태 머신에 정의된 캐릭터 현재 상태의 스테이터스입니다. | | ElapsedTime | `number` | 캐릭터가 초기화된 이후 경과한 시간(초)입니다. | ### 이벤트 | 이름 | 형식 | 설명 | | -------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | OnChangedState | `UnityEvent` | 캐릭터 상태가 변경될 때 발생하는 이벤트입니다. 등록된 리스너는 두 개의 매개변수를 받습니다: - 새로운 캐릭터 상태. (형식: `CharacterState`) - 이전 캐릭터 상태. (형식: `CharacterState`) | | OnUpdateState | `UnityEvent` | 캐릭터 상태가 `StateStatus.Update` 스테이터스일 때 발생하는 이벤트입니다. 등록된 리스너는 하나의 매개변수를 받습니다: - 현재 캐릭터 상태. (형식: `CharacterState`) | ### 메서드 ### SyncStateAnimation `SyncStateAnimation() → void` ZEPETO 캐릭터의 현재 캐릭터 상태와 Animator를 동기화합니다. ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState) → void` 전달된 캐릭터 상태에 대응하는 애니메이션을 Animator에서 재생합니다. | 매개변수 | 형식 | 설명 | | ----- | ----------------------------------- | -------------------------- | | state | [CharacterState](./#characterstate) | 재생할 애니메이션을 나타내는 캐릭터 상태입니다. | ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState, moveState: CharacterMoveState) → void` 전달된 캐릭터 상태에 대응하는 애니메이션을 Animator에서 재생합니다. | 매개변수 | 형식 | 설명 | | --------- | ------------------------------------------- | --------------------------------------------------------------- | | state | [CharacterState](./#characterstate) | 재생할 애니메이션을 나타내는 캐릭터 상태입니다. | | moveState | [CharacterMoveState](./#charactermovestate) | `state`가 `CharacterState.Move`인 경우 애니메이션에 사용할 이동 상태입니다. (선택 사항) | ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState, jumpState: CharacterJumpState) → void` 전달된 캐릭터 상태에 대응하는 애니메이션을 Animator에서 재생합니다. | 매개변수 | 형식 | 설명 | | --------- | ------------------------------------------- | --------------------------------------------------------------- | | state | [CharacterState](./#characterstate) | 재생할 애니메이션을 나타내는 캐릭터 상태입니다. | | jumpState | [CharacterJumpState](./#characterjumpstate) | `state`가 `CharacterState.Jump`인 경우 애니메이션에 사용할 점프 상태입니다. (선택 사항) | ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState, landingState: CharacterLandingState) → void` 전달된 캐릭터 상태에 대응하는 애니메이션을 Animator에서 재생합니다. | 매개변수 | 형식 | 설명 | | ------------ | ------------------------------------------------- | ------------------------------------------------------------------ | | state | [CharacterState](./#characterstate) | 재생할 애니메이션을 나타내는 캐릭터 상태입니다. | | landingState | [CharacterLandingState](./#characterlandingstate) | `state`가 `CharacterState.Landing`인 경우 애니메이션에 사용할 착지 상태입니다. (선택 사항) | ### Move `Move(dir: Vector2) → void` 지정한 방향으로 캐릭터를 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | --------- | --------------- | | dir | `Vector2` | 캐릭터가 이동할 방향입니다. | ### Move `Move(dir: Vector3) → void` 지정한 방향으로 캐릭터를 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | --------- | --------------- | | dir | `Vector3` | 캐릭터가 이동할 방향입니다. | ### MoveContinuously `MoveContinuously(dir: Vector2) → void` 현재 바라보는 방향을 기준으로 지정한 방향으로 캐릭터를 계속 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | --------- | ----------------------------------- | | dir | `Vector2` | 현재 바라보는 방향을 기준으로 한, 캐릭터가 이동할 방향입니다. | ### MoveContinuously `MoveContinuously(dir: Vector3) → void` 현재 바라보는 방향을 기준으로 지정한 방향으로 캐릭터를 계속 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | --------- | ----------------------------------- | | dir | `Vector3` | 현재 바라보는 방향을 기준으로 한, 캐릭터가 이동할 방향입니다. | ### MoveToPosition `MoveToPosition(pos: Vector3) → void` 지정한 위치로 캐릭터를 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | --------- | ---------------- | | pos | `Vector3` | 캐릭터가 이동할 목적지입니다. | ### StopMoving `StopMoving() → void` 캐릭터의 이동을 멈춥니다. ### Jump `Jump() → void` 캐릭터를 점프시킵니다. ### DoubleJump `DoubleJump() → void` 캐릭터를 더블 점프시킵니다. ### Teleport `Teleport(pos: Vector3, rot: Quaternion) → void` 지정한 Transform 위치로 캐릭터를 즉시 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | ------------ | ---------------------- | | pos | `Vector3` | 캐릭터가 텔레포트할 위치입니다. | | rot | `Quaternion` | 텔레포트 후 캐릭터가 가질 회전값입니다. | ### SetGesture `SetGesture(gesture: AnimationClip) → void` 지정한 제스처에 해당하는 캐릭터 모션을 재생합니다. | 매개변수 | 형식 | 설명 | | ------- | --------------- | --------------- | | gesture | `AnimationClip` | 캐릭터가 취할 제스처입니다. | ### CancelGesture `CancelGesture() → void` 제스처 재생을 중지합니다. ### GetSocket `GetSocket(socket: KnowSockets) → Transform` 캐릭터의 소켓에 대한 `Transform`을 가져옵니다. | 매개변수 | 형식 | 설명 | | ------ | ----------------------------- | ------------- | | socket | [KnowSockets](./#knowsockets) | 소켓(부착 지점)입니다. | **반환값:** `Transform` — 지정한 소켓에 연결된 `Transform` 컴포넌트입니다. ### GetSocket `GetSocket(socket: string) → Transform` 캐릭터의 소켓에 대한 `Transform`을 가져옵니다. | 매개변수 | 형식 | 설명 | | ------ | -------- | ----------------- | | socket | `string` | 소켓(부착 지점)의 이름입니다. | **반환값:** `Transform` — 지정한 소켓에 연결된 `Transform` 컴포넌트입니다. ### GetBodyModifierProperties `GetBodyModifierProperties() → ZepetoPropertyFlag[]` 캐릭터가 착용한 신체 변형 아이템에 연결된 캐릭터 속성을 가져옵니다. **반환값:** `ZepetoPropertyFlag[]` — 캐릭터가 착용한 신체 변형 아이템에 연결된 캐릭터 속성입니다. ### DeformDefaultProperties `DeformDefaultProperties() → void` 캐릭터가 착용한 신체 변형 아이템을 제거하고 기본 체형으로 되돌립니다. ### DeformDefaultCostume `DeformDefaultCostume() → void` 캐릭터가 착용한 신체 변형 아이템을 제거하고 기본 체형으로 되돌린 뒤, 기본 ZEPETO 의상을 적용합니다. ### add\_loadedCharacter `add_loadedCharacter(value: Action) → void` 캐릭터 로딩 완료를 처리할 콜백 함수를 추가합니다. | 매개변수 | 형식 | | ----- | -------- | | value | `Action` | ### remove\_loadedCharacter `remove_loadedCharacter(value: Action) → void` 캐릭터 로딩 완료를 처리하는 콜백 함수를 제거합니다. | 매개변수 | 형식 | | ----- | -------- | | value | `Action` | ## CameraData `class` `ZepetoCamera`의 초기 설정을 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | ---------------------- | ------------ | ------------------------------------------------------ | | cameraPrefab | `GameObject` | `ZepetoCamera`를 초기화하기 위한 프리팹입니다. | | maxZoomDistance | `number` | 카메라가 대상으로부터 줌 아웃할 수 있는 기본 최대 거리입니다. | | minZoomDistance | `number` | 카메라가 대상 쪽으로 줌 인할 수 있는 기본 최소 거리입니다. | | maxPitch | `number` | 카메라가 대상 주위를 회전할 때의 최대 수직 각도입니다. | | minPitch | `number` | 카메라가 대상 주위를 회전할 때의 최소 수직 각도입니다. | | offset | `Vector3` | 대상에 대한 카메라의 기본 오프셋입니다. | | lockXAxis | `boolean` | 카메라의 X축 회전이 잠겨 있는지 여부를 나타냅니다. | | layer | `LayerMask` | 카메라가 충돌할 수 있는 레이어를 정의합니다. | | collisionTimeThreshold | `number` | 카메라 충돌 감지의 시간 임계값입니다. 카메라가 충돌에 얼마나 빠르게 반응하는지에 영향을 줍니다. | | zoomSpeed | `number` | 줌 인과 줌 아웃의 속도입니다. | | zoomDampSpeed | `number` | 줌 인과 줌 아웃의 보간 속도입니다. | | rotationSpeed | `number` | 회전 속도입니다. | | rotationDampSpeed | `number` | 회전의 보간 속도입니다. | | characterCulling | `boolean` | 카메라가 가까울 때의 렌더링 문제를 방지하기 위해 캐릭터 컬링을 활성화할지 여부를 나타냅니다. | | targetScaleWeight | `number` | 카메라의 위치와 동작을 조정하기 위해 대상의 스케일에 적용되는 가중치입니다. | ## CharacterData `class` `ZepetoCharacter`의 초기 설정을 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | ------------------ | --------------------------------------- | ------------------------------------------------ | | slopeLimit | `number` | 캐릭터가 올라갈 수 있는 최대 경사 각도입니다. | | stepOffset | `number` | 캐릭터가 넘어갈 수 있는 최대 수직 높이 차이입니다. | | skinWidth | `number` | 충돌 감지용 스킨 두께입니다. 캐릭터가 다른 콜라이더 안으로 파고드는 것을 방지합니다. | | minMoveDistance | `number` | 캐릭터가 이동할 수 있는 최소 간격입니다. | | center | `Vector3` | 캐릭터 콜라이더의 중심점입니다. | | radius | `number` | 캐릭터 캡슐 콜라이더의 반지름입니다. | | height | `number` | 캐릭터 캡슐 콜라이더의 높이입니다. | | layer | `LayerMask` | 캐릭터가 충돌할 수 있는 레이어를 정의합니다. | | shadow | `GameObject` | 캐릭터 그림자의 시각적 표현입니다. | | animatorController | `RuntimeAnimatorController` | 캐릭터의 Animator Controller입니다. | | walkSpeed | `number` | 캐릭터의 걷기 속도입니다. | | runSpeed | `number` | 캐릭터의 달리기 속도입니다. | | jumpPower | `number` | 캐릭터의 점프력입니다. | | customMotionData | [CustomMotionData](./#custommotiondata) | 캐릭터 모션의 커스텀 설정입니다. | ## ControllerData `class` `ZepetoPlayerControl`의 설정을 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | --------------------------- | ------------------ | ---------------------------------------------------------- | | inputAsset | `InputActionAsset` | 복잡한 입력 구성을 관리하기 위한 입력 액션과 바인딩의 컨테이너입니다. | | eventSystem | `GameObject` | 사용자 입력을 처리해 UI 컴포넌트로 전달합니다. 버튼 클릭, 드래그, 드롭 등의 상호작용을 처리합니다. | | useDefaultVirtualController | `boolean` | 기본 V-Pad를 사용할지 여부를 결정합니다. | | useDefaultInputController | `boolean` | 기본 입력 컨트롤러를 사용할지 여부를 결정합니다. | | verticalController | `GameObject` | 세로 화면 방향용 V-Pad 컨트롤러 프리팹입니다. | | horizontalController | `GameObject` | 가로 화면 방향용 V-Pad 컨트롤러 프리팹입니다. | ## FloatingUIData `class` 캐릭터 관련 UI 설정을 관리하는 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | -------------------------- | --------- | ----------------------------------------- | | showNickNameLocalPlayer | `boolean` | 로컬 플레이어 캐릭터의 닉네임 UI를 표시할지 여부를 결정합니다. | | showNickNameOtherPlayers | `boolean` | 다른 플레이어 캐릭터의 닉네임 UI를 표시할지 여부를 결정합니다. | | showBubbleChatLocalPlayer | `boolean` | 로컬 플레이어 캐릭터의 말풍선 채팅 UI를 표시할지 여부를 결정합니다. | | showBubbleChatOtherPlayers | `boolean` | 다른 플레이어 캐릭터의 말풍선 채팅 UI를 표시할지 여부를 결정합니다. | | useMiniProfileOnApp | `boolean` | 캐릭터를 클릭했을 때 미니 프로필 팝업 UI를 표시할지 여부를 결정합니다. | ## LocalPlayer `class` 이동, 코스튬 커스터마이징, ZEPETO 카메라 조작 등 로컬 플레이어의 동작을 관리하기 위한 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ------------ | ------------------------------- | --------------------------------- | | movingAxis | `Transform` | 로컬 플레이어 ZEPETO 캐릭터의 이동 중심축입니다. | | zepetoCamera | [ZepetoCamera](./#zepetocamera) | 로컬 플레이어에 연결된 ZEPETO 카메라 인스턴스입니다. | | zepetoPlayer | [ZepetoPlayer](./#zepetoplayer) | 로컬 플레이어에 연결된 ZEPETO 플레이어 인스턴스입니다. | ### 메서드 ### SetCostume `SetCostume(itemCode: string, complete?: Action) → void` 로컬 플레이어 ZEPETO 캐릭터의 코스튬을 변경합니다. 일반 `Exception`을 발생시킵니다. | 매개변수 | 형식 | 설명 | | ---------------- | -------- | ----------------- | | itemCode | `string` | 코스튬의 아이템 ID입니다. | | complete (선택 사항) | `Action` | 완료를 처리할 콜백 함수입니다. | ### Jump `Jump() → void` 로컬 플레이어의 ZEPETO 캐릭터를 점프시킵니다. ### DoubleJump `DoubleJump() → void` 로컬 플레이어의 ZEPETO 캐릭터를 더블 점프시킵니다. ### Move `Move(dir: Vector2) → void` 로컬 플레이어의 ZEPETO 캐릭터를 지정한 방향으로 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | --------- | --------------- | | dir | `Vector2` | 캐릭터가 이동할 방향입니다. | ### Move `Move(dir: Vector3) → void` 로컬 플레이어의 ZEPETO 캐릭터를 지정한 방향으로 이동시킵니다. | 매개변수 | 형식 | 설명 | | ---- | --------- | --------------- | | dir | `Vector3` | 캐릭터가 이동할 방향입니다. | ### StopMoving `StopMoving() → void` 로컬 플레이어의 ZEPETO 캐릭터를 정지시킵니다. ## ZepetoCamera `class` ZEPETO Character Controller에서 사용하도록 설계된 카메라 제어 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ------------------------- | --------------------------------------------- | -------------------------------------------------------------- | | additionalMaxZoomDistance | `number` | 기본 최대 줌 값에 더해지는 추가 거리입니다. | | additionalMinZoomDistance | `number` | 기본 최소 줌 값에 더해지는 추가 거리입니다. | | additionalOffset | `Vector3` | 대상을 기준으로 한 카메라 위치에 적용되는 추가 오프셋입니다. | | currentState | [CameraState](./#camerastate) | 현재 카메라 상태를 가져옵니다. | | currentStateStatus | [StateStatus](./#statestatus) | 현재 카메라 상태의 스테이터스를 가져옵니다. | | position | `Vector3` | 현재 카메라의 위치 값을 가져옵니다. | | rotation | `Quaternion` | 현재 카메라의 회전 값을 가져옵니다. | | distance | `number` | 대상으로부터의 거리입니다. | | cameraParent | `Transform` | 카메라 부모 오브젝트의 `Transform`입니다. | | isFollow | `boolean` | 카메라가 대상을 따라가고 있는지 여부를 나타내는 플래그를 가져옵니다. | | StateMachine | [StateMachine\](./#statemachine) | 카메라의 상태 머신을 가져옵니다. | | FollowTarget | `Transform` | 대상의 `Transform`을 가져옵니다. 기본값은 로컬 플레이어 캐릭터의 `HEAD_UPPER`로 설정됩니다. | | MaxZoomDistance | `number` | 카메라가 대상으로부터 줌 아웃할 수 있는, 계산된 최대 거리입니다. | | MinZoomDistance | `number` | 카메라가 대상 쪽으로 줌 인할 수 있는, 계산된 최소 거리입니다. | | LookOffset | `Vector3` | 대상에 대한 카메라의 계산된 오프셋입니다. | | LockXAxis | `boolean` | 카메라의 X축 회전이 잠겨 있는지 여부를 나타냅니다. | | CollisionLayer | `LayerMask` | 카메라가 충돌할 수 있는 레이어를 정의합니다. | | targetScaleWeight | `number` | 카메라의 위치와 동작을 조정하기 위해 대상의 스케일에 적용되는 가중치입니다. | | useCharacterCulling | `boolean` | 카메라가 가까울 때의 렌더링 문제를 방지하기 위해 캐릭터 컬링을 활성화할지 여부를 나타냅니다. | | zoomSpeed | `number` | 줌 인과 줌 아웃의 속도입니다. | | zoomDampSpeed | `number` | 줌 인과 줌 아웃의 보간 속도입니다. | | rotationSpeed | `number` | 회전 속도입니다. | | rotationDampSpeed | `number` | 회전의 보간 속도입니다. | | camera | `Camera` | Unity `Camera`입니다. | ### 이벤트 | 이름 | 형식 | 설명 | | -------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | OnChangedState | `UnityEvent` | 카메라 상태가 변경될 때 발생하는 이벤트입니다. 등록된 리스너는 두 개의 매개변수를 받습니다: - 새로운 카메라 상태. (형식: `CameraState`) - 이전 카메라 상태. (형식: `CameraState`) | | OnUpdateState | `UnityEvent` | 현재 카메라 상태가 `StateStatus.Update` 스테이터스일 때 발생하는 이벤트입니다. 등록된 리스너는 하나의 매개변수를 받습니다: - 현재 카메라 상태. (형식: `CameraState`) | ### 메서드 ### Create `static Create(camera: Camera, data: CameraData) → ZepetoCamera` `ZepetoCamera` 인스턴스를 생성합니다. | 매개변수 | 형식 | 설명 | | ------ | --------------------------- | ------------------------------------------------ | | camera | `Camera` | `ZepetoCamera`의 기반으로 사용할 Unity `Camera` 오브젝트입니다. | | data | [CameraData](./#cameradata) | `ZepetoCamera`의 초기 설정입니다. | **반환값:** [ZepetoCamera](./#zepetocamera) — `ZepetoCamera`의 새 인스턴스입니다. ### SetFollowTarget `SetFollowTarget(target: Transform, scaleReference?: Transform) → void` 카메라가 따라갈 대상을 설정합니다. | 매개변수 | 형식 | 설명 | | ---------------------- | ----------- | ----------------------------------------------------------------------------------- | | target | `Transform` | 카메라가 따라갈 오브젝트를 나타내는 `Transform`입니다. | | scaleReference (선택 사항) | `Transform` | 카메라의 추적 동작을 스케일링하는 기준으로 사용할 `Transform`입니다. 지정하면 카메라는 이 기준의 스케일에 따라 대상과의 거리를 조정합니다. | ### Rotate `Rotate(delta: Vector2) → void` 카메라를 회전시킵니다. | 매개변수 | 형식 | 설명 | | ----- | --------- | ------- | | delta | `Vector2` | 회전량입니다. | ### DoZoom `DoZoom(delta: number) → void` 카메라를 줌합니다. | 매개변수 | 형식 | 설명 | | ----- | -------- | ------- | | delta | `number` | 줌 양입니다. | ## ZepetoPlayer `class` ZEPETO 플레이어를 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | ------------- | ------------------------------------- | -------------------------------------------- | | userId | `string` | 플레이어의 사용자 ID입니다. 계정 생성 시 무작위로 할당되는 고유 ID입니다. | | name | `string` | 플레이어의 사용자 이름입니다. ZEPETO 앱에서 사용자가 설정합니다. | | character | [ZepetoCharacter](./#zepetocharacter) | 플레이어의 ZEPETO 캐릭터입니다. | | isLocalPlayer | `boolean` | 로컬 플레이어인지 여부를 나타냅니다. | ### 메서드 ### GetProfileTextureAsync `GetProfileTextureAsync(complete: Action) → void` 플레이어의 프로필 이미지를 가져옵니다. 일반 `Exception`을 발생시킵니다. | 매개변수 | 형식 | 설명 | | -------- | ------------------- | -------------------------- | | complete | `Action` | 가져온 프로필 이미지를 처리할 콜백 함수입니다. | ### Release `Release() → void` ZEPETO 플레이어 객체를 해제합니다. ## ZepetoPlayerControl `class` ZEPETO 플레이어의 입력 제어를 관리합니다. ### 메서드 ### Create `static Create(playerActions: PlayerActions) → ZepetoPlayerControl` `ZepetoPlayerControl` 인스턴스를 생성합니다. | 매개변수 | 형식 | 설명 | | ------------- | --------------- | --------------------------------------- | | playerActions | `PlayerActions` | `ZepetoPlayerControl`에 연결할 입력 액션 세트입니다. | **반환값:** [ZepetoPlayerControl](./#zepetoplayercontrol) — `ZepetoPlayerControl`의 새 인스턴스입니다. 인스턴스가 새 게임 오브젝트에 부착되어 플레이어의 입력 액션을 처리할 수 있는 상태가 됩니다. ## ZepetoCameraControl `class` 카메라 이동과 줌의 입력 처리를 포함해 ZEPETO 환경의 카메라 조작을 관리합니다. ### 메서드 ### Create `static Create(cameraActions: CameraActions) → ZepetoCameraControl` `ZepetoCameraControl` 인스턴스를 생성합니다. | 매개변수 | 형식 | 설명 | | ------------- | --------------- | ----------------------------------------------------------------------------- | | cameraActions | `CameraActions` | `ZepetoCameraControl`에 연결할 카메라 액션 세트입니다. 이 액션들은 카메라가 사용자 입력에 어떻게 반응할지를 정의합니다. | **반환값:** [ZepetoCameraControl](./#zepetocameracontrol) — `ZepetoCameraControl`의 새 인스턴스입니다. 인스턴스가 새 게임 오브젝트에 부착되어 카메라의 입력 액션을 처리할 수 있는 상태가 됩니다. ## CharacterState `enum` ZEPETO 캐릭터의 상태를 나타냅니다. | 이름 | 값 | 설명 | | -------- | --- | -------------------------------------------- | | Invalid | 0 | 초기화되지 않았거나 유효하지 않은 상태입니다. | | Idle | 1 | 캐릭터가 어떤 이동이나 동작도 하고 있지 않은 상태입니다. | | Walk | 2 | 캐릭터가 느린 속도로 이동 중인 상태입니다. | | Run | 3 | 캐릭터가 빠르게 이동 중인 상태입니다. | | JumpIdle | 4 | 캐릭터가 제자리에서 점프 중인 상태입니다. | | JumpMove | 5 | 캐릭터가 수직 도약과 수평 이동을 결합해 특정 방향으로 점프 중인 상태입니다. | | Teleport | 20 | 캐릭터가 사이 공간을 지나지 않고 한 위치에서 다른 위치로 이동하는 상태입니다. | | Gesture | 30 | 캐릭터가 제스처를 취하고 있는 상태입니다. | | Move | 102 | 일반적인 이동 상태입니다. | | MoveTurn | 103 | 캐릭터가 이동 방향을 바꾸고 있는 상태입니다. | | Jump | 104 | 일반적인 점프 상태입니다. | | Stamp | 106 | 캐릭터가 발 구르기 동작을 하고 있는 상태입니다. | | Falling | 108 | 캐릭터가 자유 낙하 중인 상태입니다. | | Landing | 109 | 캐릭터가 낙하 후 지면으로 돌아오는 상태입니다. | ## CharacterMoveState `enum` ZEPETO 캐릭터의 세부 이동 상태를 나타냅니다. | 이름 | 값 | 설명 | | -------- | -- | ------------- | | None | -1 | None. | | MoveWalk | 0 | 느린 속도로 이동합니다. | | MoveRun | 1 | 빠르게 이동합니다. | ## CharacterJumpState `enum` ZEPETO 캐릭터의 세부 점프 상태를 나타냅니다. | 이름 | 값 | 설명 | | ---------- | -- | -------------------------------- | | None | -1 | None. | | JumpIdle | 0 | 제자리에서 점프합니다. | | JumpMove | 1 | 수직 도약과 수평 이동을 결합한, 방향이 있는 점프입니다. | | JumpDash | 2 | 빠르게 점프합니다. | | JumpDouble | 3 | 점프 중에 두 번째 점프를 수행합니다. | ## CharacterLandingState `enum` ZEPETO 캐릭터의 세부 착지 상태를 나타냅니다. | 이름 | 값 | 설명 | | ------------- | -- | ------------------ | | None | -1 | None. | | LandingSlight | 0 | 충격이 작은 착지 상태입니다. | | LandingDeep | 1 | 충격이 큰 착지 상태입니다. | | LandingRoll | 2 | 구르기를 동반한 착지 상태입니다. | ## KnowSockets `enum` 캐릭터의 알려진 부착 지점, 즉 소켓의 집합을 정의합니다. | 이름 | 값 | 설명 | | ----------- | - | ------------------- | | HEAD\_UPPER | 0 | 캐릭터 머리의 윗부분을 나타냅니다. | ## MotionState `class` 캐릭터의 모션 상태와 설정을 관리하는 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ------------------- | ------------------------------------------------- | ------------------------------------ | | useDoubleJump | `boolean` | 캐릭터가 더블 점프를 할 수 있는지 여부를 결정합니다. | | doubleJumpPower | `number` | 더블 점프 시 적용되는 추가 힘입니다. | | useLanding | `boolean` | 착지 모션을 적용할지 여부를 결정합니다. | | useLandingRoll | `boolean` | 착지 시 캐릭터가 구르기를 수행할지 여부를 결정합니다. | | landingRollSpeed | `number` | 캐릭터의 착지 구르기 속도를 가져오거나 설정합니다. | | useMoveTurn | `boolean` | 캐릭터의 이동 방향을 바꿀 때 모션을 재생할지 여부를 결정합니다. | | gravity | `number` | 캐릭터에 적용되는 중력입니다. | | currentJumpState | [CharacterJumpState](./#characterjumpstate) | 캐릭터의 현재 점프 상태를 가져옵니다. | | currentLandingState | [CharacterLandingState](./#characterlandingstate) | 캐릭터의 현재 착지 상태를 가져옵니다. | | currentMoveState | [CharacterMoveState](./#charactermovestate) | 캐릭터의 현재 이동 상태를 가져옵니다. | ## CharacterStateMachine `class` · extends [StateMachine\](./#statemachine) ZEPETO 캐릭터의 캐릭터 상태와 Animator를 동기화하는 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------ | | constraintStateAnimation | `boolean` | ZEPETO 캐릭터의 현재 캐릭터 상태와 Animator를 동기화할지 여부를 결정합니다. `true`로 설정하면 Animator 상태가 현재 캐릭터 상태를 기준으로 갱신되지 않습니다. | ### 메서드 ### SyncStateAnimation `SyncStateAnimation() → void` ZEPETO 캐릭터의 현재 캐릭터 상태와 Animator를 동기화합니다. ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState) → void` 전달된 캐릭터 상태에 대응하는 애니메이션을 Animator에서 재생합니다. | 매개변수 | 형식 | 설명 | | ----- | ----------------------------------- | -------------------------- | | state | [CharacterState](./#characterstate) | 재생할 애니메이션을 나타내는 캐릭터 상태입니다. | ## StateMachine `class` `StateMachine` manages the `States`, `Transitions`, and `Events`. 지정된 조건과 경과 시간에 따라 상태를 갱신함으로써 객체의 다양한 상태를 정의하고 제어할 수 있습니다. ### 속성 | 이름 | 형식 | 설명 | | --------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | | OnChangedState | `Action` | 카메라 상태가 변경될 때 발생하는 이벤트입니다. 등록된 리스너는 두 개의 매개변수를 받습니다: - 새로운 상태. - 이전 상태. | | Events | [TransitionBase\\[\]](./#transitionbase) | 상태 머신에 정의된 모든 이벤트의 배열을 제공합니다. | | Current | [State\](./#state) | 현재 상태를 가져옵니다. | | Prev | [State\](./#state) | 이전 상태를 가져옵니다. | | IsRunning | `boolean` | 상태 머신이 상태와 전이를 실제로 처리하고 있는지 여부를 나타냅니다. | | stateCount | `number` | 상태 머신에 정의된 상태의 개수를 가져옵니다. | | transitionCount | `number` | 상태 머신에 정의된 전이의 개수를 가져옵니다. | ### 메서드 ### FindState `FindState(state: TEnum, success: Action>, failed: Action) → void` 상태 머신에서 상태를 찾고, 성공하면 콜백을 실행합니다. | 매개변수 | 형식 | 설명 | | ------- | ---------------------- | --------------------------- | | state | `TEnum` | 상태 머신에서 찾을 상태입니다. | | success | `Action>` | 찾은 `State`를 처리할 콜백 함수입니다. | | failed | `Action` | 상태를 찾지 못한 경우를 처리할 콜백 함수입니다. | ### FindTransitions `FindTransitions(from: TEnum, success: Action[]>, failed: Action) → void` 상태 머신에서 전이들을 찾고, 성공하면 콜백을 실행합니다. | 매개변수 | 형식 | 설명 | | ------- | ----------------------------- | --------------------------------- | | from | `TEnum` | 전이가 시작되는 상태입니다. | | success | `Action[]>` | 찾은 `Transition` 배열을 처리할 콜백 함수입니다. | | failed | `Action` | 전이를 찾지 못한 경우를 처리할 콜백 함수입니다. | ### FindTransition `FindTransition(from: TEnum, to: TEnum, success: Action>, failed: Action) → void` 상태 머신에서 전이를 하나 찾고, 성공하면 콜백을 실행합니다. | 매개변수 | 형식 | 설명 | | ------- | --------------------------- | ------------------------------ | | from | `TEnum` | 전이가 시작되는 상태입니다. | | to | `TEnum` | 전이가 이루어질 대상 상태입니다. | | success | `Action>` | 찾은 `Transition`을 처리할 콜백 함수입니다. | | failed | `Action` | 해당 전이를 찾지 못한 경우를 처리할 콜백 함수입니다. | ### Start `Start(state: TEnum) → void` 상태 머신의 처리를 시작합니다. | 매개변수 | 형식 | 설명 | | ----- | ------- | --------------------- | | state | `TEnum` | 상태 머신이 처리를 시작할 상태입니다. | ### Update `Update(deltaTime: number) → void` 상태 머신의 현재 상태와 전이를 갱신합니다. | 매개변수 | 형식 | 설명 | | --------- | -------- | -------------------------------- | | deltaTime | `number` | 마지막 `Update` 호출 이후 경과한 시간(초)입니다. | ### Stop `Stop() → void` 상태 머신의 처리를 중지합니다. ### EnterState `EnterState(state: TEnum) → void` 상태 머신을 지정한 상태로 전이시킵니다. | 매개변수 | 형식 | 설명 | | ----- | ------- | -------------------- | | state | `TEnum` | 상태 머신이 전이할 대상 상태입니다. | ### LeaveState `LeaveState(nextState: TEnum) → void` 상태 머신이 현재 상태에서 빠져나옵니다. | 매개변수 | 형식 | 설명 | | --------- | ------- | -------------------------------- | | nextState | `TEnum` | 현재 상태의 `OnLeave`에서 처리할 다음 상태입니다. | ## StateStatus `enum` 상태 머신 내 상태가 가질 수 있는 스테이터스를 나타내며, 상태 생명 주기의 현재 단계를 보여줍니다. | 이름 | 값 | 설명 | | ------ | - | ------------------------------- | | Wait | 0 | 상태가 비활성이며 진입을 기다리는 상태입니다. | | Enter | 1 | 상태가 진입 처리 중인 상태입니다. | | Update | 2 | 상태가 활성이며 해당 로직이 실행 중인 상태입니다. | | End | 3 | 상태가 활성 단계를 마치고 종료할 준비가 된 상태입니다. | | Leave | 4 | 상태가 종료 처리 중인 상태입니다. | ## CustomMotionData `class` 캐릭터 모션의 커스텀 설정을 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | ----------------------------- | --------- | --------------------------------------------- | | useDoubleJump | `boolean` | 캐릭터가 더블 점프를 할 수 있는지 여부를 결정합니다. | | doubleJumpPower | `number` | 더블 점프 시 적용되는 추가 힘입니다. | | useLanding | `boolean` | 착지 모션을 적용할지 여부를 결정합니다. | | useLandingRoll | `boolean` | 착지 시 캐릭터가 구르기를 수행할지 여부를 결정합니다. | | landingRollSpeed | `number` | 착지 구르기 모션의 재생 속도입니다. | | useMoveTurn | `boolean` | 캐릭터의 이동 방향을 바꿀 때 모션을 재생할지 여부를 결정합니다. | | gravity | `number` | 캐릭터에 적용되는 중력입니다. | | walkThreshold | `number` | 걷기 모션의 가속을 발생시키는 데 필요한 최소 입력값입니다. | | runThreshold | `number` | 걷기 모션에서 달리기 모션으로 전환하는 데 필요한 최소 입력값입니다. | | fallingTimeThreshold | `number` | 캐릭터가 낙하 상태에 진입했는지 판정하기 위한 최소 낙하 시간입니다. | | fallingSpeedThreshold | `number` | 캐릭터가 낙하 상태에 진입했는지 판정하기 위한 최소 낙하 속도입니다. | | landingTimeThreshold | `number` | 캐릭터가 착지했는지 판정하기 위한 최소 착지 시간입니다. | | landingSpeedThreshold | `number` | 착지 시 캐릭터가 추가 동작을 할 수 있는지 판정하기 위한 최소 낙하 속도입니다. | | landingImpactSpeedThreshold | `number` | 착지 시 캐릭터가 더 큰 충격을 받는지 판정하기 위한 최소 낙하 속도입니다. | | landingRollSpeedThreshold | `number` | 착지 구르기를 발생시키는 데 필요한 최대 낙하 속도입니다. | | moveTurnAngleThreshold | `number` | 방향 전환 모션을 발생시키는 데 필요한 최소 회전 각도입니다. | | moveTurnSpeedThreshold | `number` | 방향 전환 모션을 발생시키는 데 필요한 최소 이동 속도입니다. | | moveTurnTimeThreshold | `number` | 방향 전환 모션의 지속 시간입니다. | | jumpDashSpeedThreshold | `number` | 대시를 발생시키는 데 필요한 최소 점프 속도입니다. | | walkClipBaseSpeed | `number` | 걷기 모션의 기본 속도입니다. | | stampClipNormalizedTime | `number` | 발 구르기 모션의 지속 시간입니다. | | landingClipNormalizedTime | `number` | 착지 모션의 지속 시간입니다. | | landingRollClipNormalizedTime | `number` | 착지 구르기 모션의 지속 시간입니다. | | moveTurnClipNormalizedTime | `number` | 방향 전환 모션의 지속 시간입니다. | ## CharacterShadow `class` ZEPETO 캐릭터의 그림자를 관리하는 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ----------------- | ----------- | ----------------------------- | | target | `Transform` | Transform 기준이 되는 오브젝트를 나타냅니다. | | autoSyncTransform | `boolean` | 그림자 위치를 대상에 동기화할지 여부를 결정합니다. | ## CameraState `enum` `ZepetoCamera`의 상태를 나타냅니다. | 이름 | 값 | 설명 | | ------ | - | ----------------------- | | Idle | 0 | 카메라가 대상을 따라가지 않는 상태입니다. | | Follow | 1 | 카메라가 대상을 따라가고 있는 상태입니다. | ## ZepetoScreenStick `class` · extends [ZepetoScreenControl](./#zepetoscreencontrol) ZEPETO 환경의 스틱 조작을 처리하기 위한 클래스입니다. ### 이벤트 | 이름 | 형식 | 설명 | | ------------------ | --------------------- | ------------------------- | | OnPointerDownEvent | `UnityEvent` | 스틱을 눌렀을 때 발생하는 이벤트입니다. | | OnDragEvent | `UnityEvent` | 스틱을 드래그하는 동안 발생하는 이벤트입니다. | | OnPointerUpEvent | `UnityEvent` | 스틱에서 손을 뗐을 때 발생하는 이벤트입니다. | ### 메서드 ### OnDrag `OnDrag(eventData: PointerEventData) → void` 드래그 동작을 관리하며, 위치 변화량을 계산해 지정된 이동 범위 내로 제한합니다. 정규화된 위치 값과 함께 `OnDragEvent`를 발생시킵니다. `ArgumentNullException`을 발생시킵니다. | 매개변수 | 형식 | 설명 | | --------- | ------------------ | -------------------- | | eventData | `PointerEventData` | 드래그 이벤트와 관련된 데이터입니다. | ## ZepetoScreenControl `class` ZEPETO 환경에서 UI 컨트롤을 만들기 위한 추상 클래스입니다. ### 메서드 ### OnPointerDown `OnPointerDown(eventData: PointerEventData) → void` 사용자가 UI 컨트롤을 눌렀을 때의 이벤트를 처리합니다. | 매개변수 | 형식 | 설명 | | --------- | ------------------ | ------------------------ | | eventData | `PointerEventData` | 포인터를 누른 이벤트와 관련된 데이터입니다. | ### OnPointerUp `OnPointerUp(eventData: PointerEventData) → void` 사용자가 UI 컨트롤에서 손을 뗐을 때의 이벤트를 처리합니다. | 매개변수 | 형식 | 설명 | | --------- | ------------------ | --------------------------- | | eventData | `PointerEventData` | 포인터에서 손을 뗀 이벤트와 관련된 데이터입니다. | ## ZepetoScreenButton `class` · extends [ZepetoScreenControl](./#zepetoscreencontrol) ZEPETO 환경의 버튼 조작을 처리하기 위한 클래스입니다. ### 이벤트 | 이름 | 형식 | 설명 | | ---------------- | ------------ | ------------------------- | | OnPointDownEvent | `UnityEvent` | 버튼을 눌렀을 때 발생하는 이벤트입니다. | | OnPointUpEvent | `UnityEvent` | 버튼에서 손을 뗐을 때 발생하는 이벤트입니다. | ## ZepetoScreenTouchpad `class` · extends [ZepetoScreenControl](./#zepetoscreencontrol) ZEPETO 환경의 터치패드 조작을 처리하기 위한 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ----------------------------- | ---------------- | ------------------------------------------------------ | | canvasGroupTouchPadBackground | `CanvasGroup` | 터치패드 배경의 불투명도와 상호작용을 관리하는 데 사용하는 Canvas Group 컴포넌트입니다. | | touchPadBackgroundCurve | `AnimationCurve` | 터치패드 배경의 페이드 인·아웃 효과에 사용하는 애니메이션 커브입니다. | | touchHandle | `RectTransform` | 터치 핸들을 나타내는 `RectTransform` 컴포넌트입니다. | | touchHandleAnimator | `Animator` | 터치 핸들을 애니메이션하는 데 사용하는 Animator 컴포넌트입니다. | | touchHandleOrigin | `RectTransform` | 터치 핸들의 원래 위치를 나타내는 `RectTransform`입니다. | | touchHandleOriginAnimator | `Animator` | 터치 핸들 원점용 Animator 컴포넌트입니다. | ### 이벤트 | 이름 | 형식 | 설명 | | ------------------ | --------------------- | --------------------------- | | OnPointerDownEvent | `UnityEvent` | 터치패드를 눌렀을 때 발생하는 이벤트입니다. | | OnDragEvent | `UnityEvent` | 터치패드를 드래그하는 동안 발생하는 이벤트입니다. | | OnPointerUpEvent | `UnityEvent` | 터치패드에서 손을 뗐을 때 발생하는 이벤트입니다. | ### 메서드 ### OnPointerClick `OnPointerClick(eventData: PointerEventData) → void` 터치패드의 클릭 이벤트를 처리합니다. `ArgumentNullException`을 발생시킵니다. | 매개변수 | 형식 | 설명 | | --------- | ------------------ | -------------------- | | eventData | `PointerEventData` | 드래그 이벤트와 관련된 데이터입니다. | ### OnDrag `OnDrag(eventData: PointerEventData) → void` 드래그 동작을 관리하며, 위치 변화량을 계산해 지정된 이동 범위 내로 제한합니다. 정규화된 위치 값과 함께 `OnDragEvent`를 발생시킵니다. `ArgumentNullException`을 발생시킵니다. | 매개변수 | 형식 | 설명 | | --------- | ------------------ | -------------------- | | eventData | `PointerEventData` | 드래그 이벤트와 관련된 데이터입니다. | ## UIZepetoPlayerControl `class` 로컬 플레이어의 캐릭터를 UI로 조작하는 기능을 제공하는 클래스입니다. ### 메서드 ### StartMoving `StartMoving() → void` 로컬 플레이어 캐릭터의 이동 플래그를 `true`로 설정합니다. ### Move `Move(delta: Vector2) → void` 로컬 플레이어 ZEPETO 캐릭터의 이동 방향을 설정합니다. | 매개변수 | 형식 | | ----- | --------- | | delta | `Vector2` | ### StopMoving `StopMoving() → void` 로컬 플레이어의 ZEPETO 캐릭터를 정지시킵니다. ### Jump `Jump() → void` 로컬 플레이어의 ZEPETO 캐릭터를 점프시킵니다. ### DoubleJump `DoubleJump() → void` 로컬 플레이어의 ZEPETO 캐릭터를 더블 점프시킵니다. ### Update `Update() → void` 로컬 플레이어 ZEPETO 캐릭터의 이동 방향을 갱신합니다. ## InputHelper `class` 입력 처리를 돕기 위한 유틸리티 클래스입니다. ### 메서드 ### IsPointerOverUIObjectCurrentPosition `static IsPointerOverUIObjectCurrentPosition() → boolean` 포인터가 현재 UI 오브젝트 위에 있는지 판정합니다. **반환값:** `boolean` — 포인터가 UI 오브젝트 위에 있으면 `true`를 반환합니다. ### IsPointerOverUIObject `static IsPointerOverUIObject(position: Vector2) → boolean` 화면상의 지정한 위치가 UI 요소 위에 있는지 확인합니다. | 매개변수 | 형식 | 설명 | | -------- | --------- | ----------- | | position | `Vector2` | 화면상의 위치입니다. | **반환값:** `boolean` — 해당 위치가 UI 오브젝트 위에 있으면 `true`를 반환합니다. ## EventReceiver `class` ZEPETO World 내의 캐릭터 관련 이벤트나 일반 이벤트를 처리하는 클래스입니다. ### 이벤트 | 이름 | 형식 | 설명 | | -------------------------------- | ----------------------------------- | ------------------------------------ | | OnCharacterClick (static) | `UnityEvent` | 캐릭터를 클릭했을 때 발생하는 이벤트입니다. | | OnCharacterProfileClick (static) | `UnityEvent` | 캐릭터의 프로필을 클릭했을 때 발생하는 이벤트입니다. | | OnClick (static) | `UnityEvent` | 다양한 인터랙티브 요소에 사용할 수 있는 범용 클릭 이벤트입니다. | ## TransitionBase `class` 상태 머신에서 상태 간 전이를 정의하기 위한 기본 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | --------- | ----------------------------- | --------------------------------------------------------------------- | | To | `TEnum` | 전이가 이루어질 대상 상태입니다. | | Duration | `number` | 전이가 시작부터 종료까지 걸리는 시간(초)입니다. | | Status | [StateStatus](./#statestatus) | 전이의 스테이터스입니다. | | IsRunning | `boolean` | 전이가 현재 `StateStatus.Enter` 또는 `StateStatus.Update` 스테이터스인지 여부를 나타냅니다. | ### 메서드 ### Check `Check() → boolean` 전이를 발생시킬 조건이 충족되었는지 확인합니다. **반환값:** `boolean` — 전이의 조건이 충족되면 `true`입니다. ## State `class` 상태 머신 내의 상태를 나타냅니다. ### 속성 | 이름 | 형식 | 설명 | | ------------- | ----------------------------- | -------------------- | | OnUpdateState | `Action` | 상태 갱신을 처리할 콜백 함수입니다. | | stateType | `TEnum` | 상태의 형식입니다. | | Status | [StateStatus](./#statestatus) | 상태의 스테이터스입니다. | ## Transition `class` · extends [TransitionBase\](./#transitionbase) 상태 머신에서 상태 간 전이를 정의하기 위한 제네릭 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ---- | ------- | --------------- | | From | `TEnum` | 전이가 시작되는 상태입니다. | ## ZepetoCharacter.LoadingStatus `enum` ZEPETO 캐릭터의 로딩 상태입니다. | 이름 | 값 | 설명 | | --------- | - | -------------------------- | | NotLoaded | 0 | 캐릭터가 아직 로딩을 시작하지 않은 상태입니다. | | Loading | 1 | 캐릭터가 로딩 중인 상태입니다. | | Loaded | 2 | 캐릭터 로딩이 완료된 상태입니다. | | Error | 3 | 로딩 과정에서 오류가 발생한 상태입니다. | ## PlayerControlMode `enum` | 이름 | 값 | | -------- | - | | Default | 0 | | WalkOnly | 1 | | RunOnly | 2 |