Studio GuideWorld SDK Guide
Log In

Using V-pad

V-pad

A control UI is required to manipulate the character within the world.

ZEPETO World basically creates a control UI called V-pad at runtime through ZEPETOPlayers.


The V-pad can perform the following functions depending on the area the player touches on the screen:


  1. Screen touch pad: When you touch the pad area and slide it up, down, left, or right, the local player moves along the XZ axis.
  • When you tap within the pad area, the touchpad appears at the touched location, and it disappears once the touch action is complete.
  • The default pad areas are as follows:
Screen modeCanvas sizeArea size
Horizontal1334 X 750600 X 450
Vertical750 X 1334375 X 500

  1. Jump button: Pressing the button causes the local player to jump. The height value of jumping can be changed through Zepeto Players > Character > Jump Power.

👍

Tips

The pad area can be changed by setting the area of the prefab registered in Control of Zepeto Players.

Change the size of the area in the following order.

  1. Select the default prefab registered in Control of Zepeto Players and copy the prefab by dragging and dropping it into Assets.
  2. Select the Pad object inside the copied Prefab.
  3. Change the Width and Height of the Rect Transform component to the desired size.

The object structure of V-pad created at runtime is as follows.

  1. Pad: A screen UI object that can move the character position.
  • Background : A translucent black background image showing the pad area.
  • HandleOrigin : The outer circle area of the pad. HandleOrigin changes position depending on the touched location.
  • Handle : The inner circle area of the pad. When the Handle is touched and dragged, its position changes and it does not leave the HandleOrigin area.
  1. Jump : A button object that allows the character to jump.
  • Up : Jump image object inside the Jump button.

How to get V-pad input value

In order to receive V-pad input values, you must access the ZepetoScreenTouchpad component and ZepetoScreenButton component created at runtime and register an event.

ZepetoScreenTouchpad Event

The ZepetoScreenButton component is a character jump button component. Accessible events include:

EventDescription
OnPointerDownEventThis event occurs when the user presses the V-pad.
OnDragEventThis event occurs while the user is pressing the V-pad.
OnPointerUpEventThis event occurs when the user releases the V-Pad.

ZepetoScreenButton Event

The ZepetoScreenButton component is a character jump button component. Accessible events include:

EventDescription
OnPointDownEventThis event occurs when the user presses the jump button.
OnPointUpEventThis event occurs when the user releases the jump button.

Example Script

The following script is an example of outputting the V-pad position value to the console when the user presses the touchpad.

import { Object } from 'UnityEngine';
import { ZepetoPlayers, ZepetoScreenButton, ZepetoScreenTouchpad } from 'ZEPETO.Character.Controller';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'

export default class GetVPadInput extends ZepetoScriptBehaviour {

    Start() {

        // Add a listener for the event when a local player is added
        ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
            this.GetPadTouch();
            this.GetJumpTouch();
        });
    }

    GetPadTouch() {

        // Find the ZepetoScreenTouchpad object in the scene
        const touchPad = Object.FindObjectOfType<ZepetoScreenTouchpad>();

        // Add a listener for the drag event on the touchpad
        touchPad.OnDragEvent.AddListener(() => {
            // Log the position of the touch handle when a drag event occurs
            console.log(touchPad.touchHandle.transform.position);
        });
    }

    GetJumpTouch() {

        // Find the ZepetoScreenButton object in the scene
        const screenButton = Object.FindObjectOfType<ZepetoScreenButton>();

        // Add a listener to the OnPointDownEvent of the screenButton
        // This listener logs "Jump Button Down" when the button is pressed
        screenButton.OnPointDownEvent.AddListener(() => {

            console.log("Jump Button Down");
        });

        // Add a listener to the OnPointUpEvent of the screenButton
        // This listener logs "Jump Button Up" when the button is released
        screenButton.OnPointUpEvent.AddListener(() => {

            console.log("Jump Button Up");
        });

    }

}
  • Script Description
    • Register an event listener that calls the GetPadTouch() and GetJumpTouch() functions when a local player is added to the scene.
    • The GetPadTouch() function is a function that processes touch events that occur on the touchpad.
      • Use Object.FindObjectOfType<ZepetoScreenTouchpad>() to find a ZepetoScreenTouchpad object in the scene.
      • Add a listener for the touchpad's OnDragEvent. This listener fires when a drag event occurs on the touchpad.
      • Within the listener, the location of the touch handle is output to the console.
    • The GetJumpTouch() function is a function that processes events that occur from the jump button.
      • Use Object.FindObjectOfType<ZepetoScreenButton>() to find a ZepetoScreenButton object in the scene.
      • Add listeners for the OnPointDownEvent and OnPointUpEvent of the jump button.
      • Within OnPointDownEvent, a log called Jump Button Down is output every time the jump button is pressed.
      • Within OnPointUpEvent, a log called Jump Button Up is output whenever the jump button is released.

  • If you run it by pressing the Play button, you can see the V-pad position value displayed in the console log every time you press the V-pad. You will also see the console log displayed every time you press or release the jump button.

V-Pad Customize

You can control the V-Pad using ScreenTouchPad and ScreenButton.

You can turn V-Pad On/Off from UIController_TouchPad_Horizontal, and UIController_TouchPad_Vertical Prefab.

Below is how it looks with Touch Pad turned off. You can turn the Jump Button off the same way.


Double Jump Setting


You can add a double jump function to the V-pad's jump button or apply a custom double jump button function.


To enable the double jump feature, activate the Custom Parameters > Double Jump checkbox in the Character section of the ZepetoPlayers component.

  • The height of the double jump can be set by adjusting the Power value.

There are three ways to use double jump feature on the V-pad:


1) Setting through V-Pad Prefab

When using Double Jump with the V-Pad Button, set up as follows.

Click the UIController_TouchPad_Vertical or UIController_TouchPad_Horizontal prefab. You will be moved to the folder where the original prefab is located under the Packages folder in the Project panel.


Copy the UIController_TouchPad_Vertical or UIController_TouchPad_Horizontal prefab by dragging and dropping it into the Assets folder.

❗️

Caution

The original prefab in the Packages folder cannot be modified, so you must copy a copy to the Assets folder to modify it.
If you try to modify the original Prefab, an Immutable Prefab error will occur.


Double-click the UIController_TouchPad_Vertical or UIController_TouchPad_Horizontal prefab in the copied Prefab item or press the Open Prefab button in the Inspector window to edit the Prefab.


Select the Jump object from the Prefab's sub-objects.


In the Zepeto Screen Button component of the Jump object, press the + button in On Point Down Event() and register an event as follows.

  • On Point Down Event()
    • Runtime Only
    • Select Object : Register UIController_TouchPad_Vertical or UIController_TouchPad_Horizontal.
    • Event Function : Click the No Function section and set it to UIZepetoPlayerControl > DoubleJump() function.

If the settings are as follows, it is successful.


2) Setting using a script

This script allows the character to perform a double jump in response to input from the V-pad's jump button.

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<ZepetoScreenButton>();
 
            // 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();
                }
            });
        })    
    }
}


Script description

  • ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener() registers a listener that is triggered when a local player is added to the game. This serves to configure the double jump feature to be added as local players are added.
  • ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character provides access to the local player's character. Object.FindObjectOfType() locates a ZepetoScreenButton type object in the current scene and assigns it to jump actions.
  • ScreenButton.OnPointDownEvent.AddListener() adds a listener to the screen button's OnPointDownEvent. This listener waits for either a screen touch or click event and initiates a jump or double jump action.
  • Within the listener, the if statement checks if the character's current state is CharacterState.Jump. If true, it executes zepetoCharacter.DoubleJump().

After writing the script, create an empty GameObject in the scene and add the DobuleJump.ts script as a component.


3) Setting through a Custom Button

If you choose to create and use your own button, please add the script as shown below.

This script adds jump and double jump functions to user-defined buttons.

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() {
 
        // Create character
        ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
            this.zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character;
        });
 
        // Add script component
        this.shotButton.onClick.AddListener(() => {
            if (this.zepetoCharacter.CurrentState === CharacterState.Jump) {
                this.zepetoCharacter.DoubleJump();
            } else {
                this.zepetoCharacter.Jump();
            }
        });
    }
}

Script description

  • ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener() registers a function to be executed when a local player is added to the game.
  • this.shotButton.onClick.AddListener() adds a function to be executed when the shotButton is clicked.
  • When the function is triggered, it checks whether the character's current state is a jump state and executes a jump or double jump.
  • If the character is in a jumping state, this.zepetoCharacter.DoubleJump() is called to perform a double jump; otherwise, this.zepetoCharacter.Jump() is called to perform a jump.

After writing the script, create an empty GameObject in the scene and add the JumpButton.ts script as a component.

Finally, assign a jump button to the Shot Button in the Inspector.