--- title: V-pad 사용하기 slug: world-sdk-guide-kr/v-pad docTags: createdAt: 2024-09-02T08:34:13.135Z --- ## V-pad 월드 내에서 캐릭터를 조작하기 위해 제어 UI가 필요합니다. ZEPETO World는 기본적으로 ZEPETOPlayers를 통해 런타임에 V-pad라는 제어 UI를 생성합니다. V-pad는 플레이어가 화면에서 터치하는 영역에 따라 다음과 같은 기능을 수행할 수 있습니다: ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-aWeQF-AtPfnvxRWh1BjEs-20240904-102410.png) 1\) 스크린 터치 패드: 패드 영역을 터치하고 위, 아래, 왼쪽 또는 오른쪽으로 슬라이드하면 로컬 플레이어가 XZ 축을 따라 이동합니다. - 패드 영역 내에서 탭하면 터치패드가 터치한 위치에 나타나고, 터치 동작이 완료되면 사라집니다. - 기본 패드 영역은 다음과 같습니다: | **스크린 모드** | **캔버스 크기** | **영역 크기** | | ---------- | ---------- | --------- | | 수평 | 1334 X 750 | 600 X 450 | | 수직 | 750 X 1334 | 375 X 500 | 2\) 점프 버튼: 버튼을 누르면 로컬 플레이어가 점프합니다. 점프의 높이 값은 Zepeto Players > Character > Jump Power를 통해 변경할 수 있습니다. :::hint{type="success"} **👍 팁** 패드 영역은 Zepeto Players의 Control에 등록된 프리팹의 영역을 설정하여 변경할 수 있습니다. 다음 순서로 영역의 크기를 변경하세요. 1. Control of Zepeto Players에 등록된 기본 프리팹을 선택하고, Assets로 드래그 앤 드롭하여 프리팹을 복사합니다. 2. 복사한 프리팹 안의 Pad 객체를 선택합니다. 3. Rect Transform 컴포넌트의 너비와 높이를 원하는 크기로 변경합니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-PzL43bMmADc3XusmuveLJ-20240904-102409.png) ::: 런타임에 생성된 V-pad의 객체 구조는 다음과 같습니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-puYNL9Hqefz7ZyItxuF58-20240904-102409.png) - 1\) 패드: 캐릭터 위치를 이동할 수 있는 화면 UI 객체입니다. - 배경: 패드 영역을 보여주는 반투명 검은 배경 이미지입니다. - 핸들 원점: 패드의 외부 원형 영역입니다. 핸들 원점은 터치된 위치에 따라 위치가 변경됩니다. - 핸들: 패드의 내부 원형 영역입니다. 핸들이 터치되고 드래그되면 위치가 변경되며 핸들 원점 영역을 벗어나지 않습니다. - 2\) 점프: 캐릭터가 점프할 수 있게 해주는 버튼 객체입니다. - 위: 점프 버튼 안의 점프 이미지 객체입니다. ## V-pad 입력 값 가져오는 방법 V-pad 입력 값을 받으려면 런타임에 생성된 ZepetoScreenTouchpad 구성 요소와 ZepetoScreenButton 구성 요소에 접근하고 이벤트를 등록해야 합니다. ### ZepetoScreenTouchpad 이벤트 ZepetoScreenButton 구성 요소는 캐릭터 점프 버튼 구성 요소입니다. 접근 가능한 이벤트는 다음과 같습니다: | **이벤트** | **설명** | | ------------------ | ----------------------------------- | | OnPointerDownEvent | 사용자가 V-pad를 누를 때 이 이벤트가 발생합니다. | | OnDragEvent | 사용자가 V-pad를 누르고 있는 동안 이 이벤트가 발생합니다. | | OnPointerUpEvent | 사용자가 V-Pad를 놓을 때 이 이벤트가 발생합니다. | ### ZepetoScreenButton 이벤트 ZepetoScreenButton 컴포넌트는 캐릭터 점프 버튼 컴포넌트입니다. 접근 가능한 이벤트는 다음과 같습니다: | **이벤트** | **설명** | | ---------------- | ----------------------------- | | OnPointDownEvent | 사용자가 점프 버튼을 누를 때 발생하는 이벤트입니다. | | OnPointUpEvent | 사용자가 점프 버튼을 놓을 때 발생하는 이벤트입니다. | ### 예제 스크립트 다음 스크립트는 사용자가 터치패드를 누를 때 V-pad 위치 값을 콘솔에 출력하는 예제입니다. :::CodeblockTabs GetVPadInput ```typescript import { Object } from 'UnityEngine'; import { ZepetoPlayers, ZepetoScreenButton, ZepetoScreenTouchpad } from 'ZEPETO.Character.Controller'; import { ZepetoScriptBehaviour } from 'ZEPETO.Script' export default class GetVPadInput extends ZepetoScriptBehaviour { Start() { // 로컬 플레이어가 추가될 때 이벤트 리스너 추가 ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => { this.GetPadTouch(); this.GetJumpTouch(); }); } GetPadTouch() { // 씬에서 ZepetoScreenTouchpad 객체 찾기 const touchPad = Object.FindObjectOfType(); // 터치패드의 드래그 이벤트에 대한 리스너 추가 touchPad.OnDragEvent.AddListener(() => { // 드래그 이벤트가 발생할 때 터치 핸들의 위치 로그 console.log(touchPad.touchHandle.transform.position); }); } GetJumpTouch() { // 씬에서 ZepetoScreenButton 객체 찾기 const screenButton = Object.FindObjectOfType(); // screenButton의 OnPointDownEvent에 리스너 추가 // 이 리스너는 버튼이 눌릴 때 "점프 버튼 다운"을 로그 screenButton.OnPointDownEvent.AddListener(() => { console.log("점프 버튼 다운"); }); // screenButton의 OnPointUpEvent에 리스너 추가 // 이 리스너는 버튼이 놓일 때 "점프 버튼 업"을 로그 screenButton.OnPointUpEvent.AddListener(() => { console.log("점프 버튼 업"); }); } } ``` ::: - 스크립트 설명 - 이벤트 리스너를 등록하여 `GetPadTouch()` 및 `GetJumpTouch()` 함수를 호출하도록 합니다. 이는 로컬 플레이어가 장면에 추가될 때 발생합니다. - 이 `GetPadTouch()` 함수는 터치패드에서 발생하는 터치 이벤트를 처리하는 함수입니다. - ZepetoScreenTouchpad 객체를 찾기 위해 `Object.FindObjectOfType()`를 사용합니다. - 터치패드의 `OnDragEvent`. 이 리스너는 터치패드에서 드래그 이벤트가 발생할 때 실행됩니다. - 리스너 내에서 터치 핸들의 위치가 콘솔에 출력됩니다. - 이 `GetJumpTouch()` 함수는 점프 버튼에서 발생하는 이벤트를 처리하는 함수입니다. - ZepetoScreenButton 객체를 찾기 위해 `Object.FindObjectOfType()`를 사용합니다. - 점프 버튼의 OnPointDownEvent 및 OnPointUpEvent에 리스너를 추가합니다. - OnPointDownEvent 내에서 점프 버튼이 눌릴 때마다 Jump Button Down이라는 로그가 출력됩니다. - OnPointUpEvent 내에서 점프 버튼이 릴리스될 때마다 Jump Button Up이라는 로그가 출력됩니다. - 재생 버튼을 눌러 실행하면 V-pad를 누를 때마다 콘솔 로그에 V-pad 위치 값이 표시됩니다. 점프 버튼을 누르거나 놓을 때마다 콘솔 로그도 표시됩니다. ::Image[]{src="https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-oG-K2Vj7dzIK0rZt4m30E-20240904-102410.gif" size="74" width="600" height="523" position="center" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-eUCWzI2PWH_E55qeF6pyb-20240904-102409.gif" size="82" width="600" height="523" position="center" showCaption="false"} ## V-Pad 사용자 정의 ScreenTouchPad와 ScreenButton을 사용하여 V-Pad를 제어할 수 있습니다. UIController\_TouchPad\_Horizontal 및 UIController\_TouchPad\_Vertical Prefab에서 V-Pad를 켜거나 끌 수 있습니다. 아래는 터치 패드가 꺼진 상태의 모습입니다. 점프 버튼도 같은 방법으로 끌 수 있습니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-ZWaRZnCyLCoAs2t3HUH4K-20240904-102409.png) ## 더블 점프 설정 V-pad의 점프 버튼에 더블 점프 기능을 추가하거나 사용자 정의 더블 점프 버튼 기능을 적용할 수 있습니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-GFpyWVkrANXO0VPHox-q1-20240904-102410.gif) 더블 점프 기능을 활성화하려면 ZepetoPlayers 구성 요소의 캐릭터 섹션에서 사용자 정의 매개변수 > 더블 점프 체크박스를 활성화하세요. - 더블 점프의 높이는 파워 값을 조정하여 설정할 수 있습니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-GBmfx3ZmDLCMgCOvVfY9v-20240904-102409.png) V-패드에서 더블 점프 기능을 사용하는 방법은 세 가지가 있습니다: ### 1) V-Pad 프리팹을 통한 설정 V-Pad 버튼으로 더블 점프를 사용할 때는 다음과 같이 설정합니다. UIController\_TouchPad\_Vertical 또는 UIController\_TouchPad\_Horizontal 프리팹을 클릭합니다. 그러면 프로젝트 패널의 패키지 폴더 아래에 있는 원본 프리팹이 위치한 폴더로 이동합니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-OPe4sz7RjAk0s4kknDCGE-20240904-102409.png) UIController\_TouchPad\_Vertical 또는 UIController\_TouchPad\_Horizontal 프리팹을 복사하여 자산 폴더로 드래그 앤 드롭합니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-P74OvPYftGrGR6-MZEO9P-20240904-102409.png) :::hint{type="danger"} **❗️ 주의** 패키지 폴더의 원본 프리팹은 수정할 수 없으므로, 수정하려면 복사본을 에셋 폴더에 복사해야 합니다. 원본 프리팹을 수정하려고 하면 불변 프리팹 오류가 발생합니다. ::Image[]{src="https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-IFEna9I6kZ5ltiW4OGxTe-20240904-102409.png" size="66" width="524" height="470" position="center" showCaption="false"} ::: 복사한 프리팹 항목에서 UIController\_TouchPad\_Vertical 또는 UIController\_TouchPad\_Horizontal 프리팹을 더블 클릭하거나 인스펙터 창에서 Open Prefab 버튼을 눌러 프리팹을 편집합니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-ghHINRGChptXnEp-Gx2t--20240904-102409.png) 프리팹의 하위 객체에서 점프 객체를 선택합니다. ::Image[]{src="https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-I6IXmbnxEwhPHbBaiCLd4-20240904-102409.png" size="60" width="482" height="366" position="center" showCaption="false"} Jump 객체의 Zepeto Screen Button 구성 요소에서 On Point Down Event()의 + 버튼을 눌러 다음과 같이 이벤트를 등록합니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-AI84IiVL045TcaFojqihM-20240904-102409.png) - On Point Down Event() - 런타임 전용 - 객체 선택: UIController\_TouchPad\_Vertical 또는 UIController\_TouchPad\_Horizontal을 등록합니다. - 이벤트 함수: No Function 섹션을 클릭하고 UIZepetoPlayerControl > `DoubleJump()` 함수로 설정합니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-j-suGhMY6tRffHIzK2Puc-20240904-102409.png) 설정이 다음과 같으면 성공입니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-WBVuAK01mslvkJTfurw94-20240904-102409.png) ### 2) 스크립트를 사용한 설정 이 스크립트는 캐릭터가 V패드의 점프 버튼 입력에 반응하여 더블 점프를 수행할 수 있게 합니다. ```typescript import { ZepetoScriptBehaviour } from 'ZEPETO.Script'; import { Object } from 'UnityEngine'; import { ZepetoScreenButton, CharacterState, ZepetoPlayers } from 'ZEPETO.Character.Controller'; export default class DobuleJump extends ZepetoScriptBehaviour { Start() { // Listen for when a local player is added and execute the given lambda function ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => { // Retrieve the local player's character const zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character; // Find an object of type ZepetoScreenButton in the scene const screenButton = Object.FindObjectOfType(); // Add a listener for the OnPointDownEvent of the screen button to handle jump actions screenButton.OnPointDownEvent.AddListener(() => { // If the character's current state is Jump, trigger a double jump if (zepetoCharacter.CurrentState === CharacterState.Jump) { zepetoCharacter.DoubleJump(); } }); }) } } ``` 스크립트 설명 - `ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener()`는 로컬 플레이어가 게임에 추가될 때 트리거되는 리스너를 등록합니다. 이는 로컬 플레이어가 추가될 때 더블 점프 기능을 구성하는 역할을 합니다. - `ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character`는 로컬 플레이어의 캐릭터에 접근할 수 있게 해줍니다.`Object.FindObjectOfType()`는 현재 씬에서 ZepetoScreenButton 타입의 객체를 찾아 점프 동작에 할당합니다. - `ScreenButton.OnPointDownEvent.AddListener()`는 화면 버튼의 OnPointDownEvent에 리스너를 추가합니다. 이 리스너는 화면 터치 또는 클릭 이벤트를 기다리며 점프 또는 더블 점프 동작을 시작합니다. - 리스너 내에서 if 문은 캐릭터의 현재 상태가 CharacterState.Jump인지 확인합니다. 만약 참이라면, `zepetoCharacter.DoubleJump()`. 스크립트를 작성한 후, 씬에 빈 GameObject를 만들고 DobuleJump.ts 스크립트를 컴포넌트로 추가하세요. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-EWB1cSxV1eVw6JfEN0wei-20240904-102409.png) ### 3) 사용자 정의 버튼을 통한 설정 자신만의 버튼을 만들고 사용하기로 선택한 경우, 아래와 같이 스크립트를 추가하십시오. 이 스크립트는 사용자 정의 버튼에 점프 및 더블 점프 기능을 추가합니다. ```typescript import { ZepetoScriptBehaviour } from 'ZEPETO.Script'; import { Button } from 'UnityEngine.UI'; import { CharacterState, ZepetoCharacter, ZepetoPlayers } from 'ZEPETO.Character.Controller'; export default class JumpButton extends ZepetoScriptBehaviour { public shotButton: Button; private zepetoCharacter: ZepetoCharacter; Start() { // 캐릭터 생성 ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => { this.zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character; }); // 스크립트 컴포넌트 추가 this.shotButton.onClick.AddListener(() => { if (this.zepetoCharacter.CurrentState === CharacterState.Jump) { this.zepetoCharacter.DoubleJump(); } else { this.zepetoCharacter.Jump(); } }); } } ``` 스크립트 설명 - `ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener()` 게임에 로컬 플레이어가 추가될 때 실행될 함수를 등록합니다. - `this.shotButton.onClick.AddListener()` shotButton이 클릭될 때 실행될 함수를 추가합니다. - 함수가 트리거되면 캐릭터의 현재 상태가 점프 상태인지 확인하고 점프 또는 더블 점프를 실행합니다. - 캐릭터가 점프 상태에 있다면, `this.zepetoCharacter.DoubleJump()` 더블 점프를 수행하기 위해 호출됩니다; 그렇지 않으면, `this.zepetoCharacter.Jump()` 점프를 수행하기 위해 호출됩니다. 스크립트를 작성한 후, 씬에 빈 GameObject를 생성하고 JumpButton.ts 스크립트를 컴포넌트로 추가합니다. 마지막으로, 인스펙터에서 점프 버튼을 샷 버튼에 할당합니다. ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-dMmQ2x_7Oke4Kw03GzV0I-20240904-102410.png)