Studio GuideWorld SDK Guide
Log In
World SDK Guide

ZEPETO Character

ZEPETOCharacter is basic ZEPETO character instance unit for loading in a World Scene.

To control the ZepetoCharacter, add the following import statement to the script.

import { ZepetoCharacter } from 'ZEPETO.Character.Controller';

ZepetoCharacter API

This API creates and removes ZEPETO character instances, including animator controller and character controller components.

APIDescription
CreateByZepetoId(zepetoId: string, spawnInfo: SpawnInfo, complete: System.Action$1)Use a ZEPETO ID to generate a ZEPETO character instance. Mainly used for NPC character creation.
CreateByUserId(userId: string, spawnInfo: SpawnInfo, complete: System.Action$1)Create a ZEPETO character instance with UserId. Mainly used for NPC character creation.
RemoveCharacter(character: ZepetoCharacter)Delete the character instance.

This API creates ZEPETO character model instances, excluding the Animator Controller and Character Controller components.

APIDescription
CreateModelByZepetoId(zepetoId: string, spawnInfo: SpawnInfo, complete: System.Action$1<UnityEngine.GameObject>)Create a ZEPETO character model GameObject with ZepetoId.

Since it is a GameObject, please use Object.Destroy() when deleting it.
CreateModelByUserId(userId: string, spawnInfo: SpawnInfo, complete: System.Action$1<UnityEngine.GameObject>)Create a ZEPETO character model GameObject with UserId.

Since it is a GameObject, please use Object.Destroy() when deleting it.

👍

  • ZEPETO ID : This is the ID value that the user directly specifies and uses within the ZEPETO app.
  • User ID : This is a unique ID value that distinguishes users within the ZEPETO system, and is not a value exposed on the UI. You can check it using a script.

If you're interested in the ZepetoCharacter API, refer to the documentation:

📘


Create/Delete Character

import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { SpawnInfo, ZepetoCharacter, ZepetoCharacterCreator } from 'ZEPETO.Character.Controller';
import { Button } from 'UnityEngine.UI';
import { GameObject, Object, Vector3 } from 'UnityEngine';
import { WorldService } from 'ZEPETO.World';
 
export default class SampleScript extends ZepetoScriptBehaviour {
 
    public zepetoId: string;
    public removeCloneCharacterButton : Button;
    public removeCloneCharacterModelButton : Button;
 
    private _cloneCharacter : ZepetoCharacter;
    private _cloneCharacterModel : GameObject;
 
    Start() {
        // Create a new instance of the SpawnInfo class
        const firstCloneSpawnInfo = new SpawnInfo();
        firstCloneSpawnInfo.position = new Vector3(0,0,1);
 
        const secondCloneSpawnInfo = new SpawnInfo();
        secondCloneSpawnInfo.position = new Vector3(0,0,3);
 
 
 
        // Create a `ZepetoCharacter` using ZepetoId
        ZepetoCharacterCreator.CreateByZepetoId(this.zepetoId, firstCloneSpawnInfo, (character: ZepetoCharacter) => {
            this._cloneCharacter = character;
        });
 
 
        // Create a `ZepetoCharacterModel` using ZepetoId
        ZepetoCharacterCreator.CreateModelByZepetoId(this.zepetoId, secondCloneSpawnInfo, (object) => {
            this._cloneCharacterModel = object;
        });
 
        // Create a `ZepetoCharacter` using UserId
        /*
        ZepetoCharacterCreator.CreateByUserId(WorldService.userId, new SpawnInfo(), (character: ZepetoCharacter) => {
            this._cloneCharacter = character;
        })
  
        // Create a `ZepetoCharacterModel` using UserId
        ZepetoCharacterCreator.CreateModelByUserId(WorldService.userId, new SpawnInfo(), (object) => {
            this._cloneCharacterModel = object;
        })
        */
 
        // Set up a click event for the `removeCloneCharacterButton` to remove the clone character.
        this.removeCloneCharacterButton.onClick.AddListener(() => {
            ZepetoCharacterCreator.RemoveCharacter(this._cloneCharacter);
        });
 
        // Set up a click event for the `removeCloneCharacterModelButton` to destroy the clone character model.
        this.removeCloneCharacterModelButton.onClick.AddListener(() => {
            Object.Destroy(this._cloneCharacterModel);
        });
    }
 
}

If you run the example, you can see that the CharacterModel on the left is created without the Animator Controller and Character Controller components as shown below.


Control Character

An interface where you can directly control the character will be provided through the script from a character instance in a Scene.

APIDescription
MoveToPosition(position : Vector3)Move the character to Position.
MoveContinuously(direction : Vector3)Move continuously (update) in the direction the character is looking at.
MoveContinuously(direction : Vector2)Move continuously (update) in the direction the character is looking at.
StopMoving()Stop the character from moving.
Jump()Character jumps to the Jump Power set.
DoubleJump()Character double jumps with the currently set DoubleJump Power. (Applicable only when using MotionController V2)
Teleport(position: UnityEngine.Vector3, rotation: UnityEngine.Quaternion)Character instantly moves to Transform.
SetGesture(gesture: UnityEngine.AnimationClip)For the specified AnimationClip, the character motion is played.

While SetGesture is running, the user's control inputs are not applied to the character.

When AnimationClip's loop option is turned on, it continues to play until CancelGesture() is called.
CancelGesture()Stop playback of the currently playing Animation Clip through SetGesture().

When CancelGesture() is executed, the user's control input is applied to the character control again.

Control Character example code.

import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import {SpawnInfo, ZepetoCharacter, ZepetoCharacterCreator} from "ZEPETO.Character.Controller";
import { WorldService } from 'ZEPETO.World';
import {AnimationClip, Vector3, WaitForSeconds } from 'UnityEngine';
 
export default class CharacterActionSample extends ZepetoScriptBehaviour {
 
    public targetPosition: Vector3;
    public danceGesture: AnimationClip;
    private _cloneCharacter: ZepetoCharacter;
 
    Start() {
 
        // Create a `ZepetoCharacter` using `ZepetoCharacterCreator.CreateByUserId`.
        ZepetoCharacterCreator.CreateByUserId(WorldService.userId, new SpawnInfo(), (character: ZepetoCharacter) => {
            // Assign the created character to `_cloneCharacter`.
            this._cloneCharacter = character;
 
            // Execute `ActionCoroutine()` as a coroutine.
            this.StartCoroutine(this.ActionCoroutine());
        })
    }
 
    *ActionCoroutine() {
 
        yield new WaitForSeconds(3);
 
        // Move `_cloneCharacter` to `targetPosition` after Wait for 3 seconds.
        this._cloneCharacter.MoveToPosition(this.targetPosition);
 
        yield new WaitForSeconds(1);
 
        // Make `_cloneCharacter` jump after Wait for 1 seconds.
        this._cloneCharacter.Jump();
 
        yield new WaitForSeconds(1);
 
        // Set the gesture of `_cloneCharacter` to `danceGesture` after Wait for 1 seconds.
        this._cloneCharacter.SetGesture(this.danceGesture);
 
        yield new WaitForSeconds(3);
 
        // Cancel the gesture of `_cloneCharacter` after Wait for 3 seconds.
        this._cloneCharacter.CancelGesture();
    }
 
}

If you run the example, you can see that the cloned character performs the specified actions in order as follows.

📘

Please refer to the following guide. [Creating and Controlling NPC]


Motion State

The API related to the Motion State of the ZEPETO character is as follows:

APIDescription
motionState.useDoubleJump = (boolean);Set whether the character can use DoubleJump.
motionState.doubleJumpPower = (number);Set the character's DoubleJump power.
motionState.useLandingRoll = (boolean);Set whether to use the character's LandingRoll.
motionState.landingRollSpeed = (number);Set the character's LandingRoll speed value.
motionState.useMoveTurn = (boolean);Set whether to use MoveTurn for the character.
motionState.Gravity = (number);Set the character's gravity value.
motionState.CurrentJumpStateYou can check the character's current jumping state.

- None = -1, JumpIdle = 0, JumpMove = 1, JumpDash = 2, JumpDouble = 3
motionState.CurrentLandingStateYou can check the character's current landing status.

- None = -1, LandingSlight = 0, LandingDeep = 1, LandingRoll = 2
motionState.CurrentMoveStateYou can check the current movement status of your character.

- None = -1, MoveWalk = 0, MoveRun = 1

Motion State example code

import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import { CustomMotionData, SpawnInfo, ZepetoCharacter, ZepetoCharacterCreator, ZepetoPlayer, LocalPlayer, ZepetoPlayers } from "ZEPETO.Character.Controller";
import { WorldService } from 'ZEPETO.World';
import { Button } from 'UnityEngine.UI';
 
export default class MotionSample extends ZepetoScriptBehaviour {
     
    public jumpButton : Button;
    private _cloneCharacter: ZepetoCharacter;
 
    Start() {
        ZepetoCharacterCreator.CreateByUserId(WorldService.userId, new SpawnInfo(), (character: ZepetoCharacter) => {
            // Assign the created character to `_cloneCharacter`.
            this._cloneCharacter = character;
 
            // Set various properties of `motionState` in `_cloneCharacter`.
            this._cloneCharacter.motionState.useDoubleJump = true;
            this._cloneCharacter.motionState.useDoubleJump = true;
            this._cloneCharacter.motionState.useLandingRoll = true;
            this._cloneCharacter.motionState.useMoveTurn = true;
            this._cloneCharacter.motionState.gravity = 1;
        })
         
        this.jumpButton.onClick.AddListener(() => {
            this._cloneCharacter.Jump();
        });
    }
 
    Update() {
        // Check if `_cloneCharacter` is not null.
        if (this._cloneCharacter != null) {
            // Print the current jump state of `motionState` in `_cloneCharacter`.
            console.log(`Current Jump State: ${this._cloneCharacter.motionState.currentJumpState}`);
 
            // Print the current landing state of `motionState` in `_cloneCharacter`.
            console.log(`Current Landing State: ${this._cloneCharacter.motionState.currentLandingState}`);
 
            // Print the current move state of `motionState` in `_cloneCharacter`.
            console.log(`Current Move State: ${this._cloneCharacter.motionState.currentMoveState}`);
        }
    }
}

Controlling ZEPETO Character Animator

API to control ZEPETO character animator

APIDescription
StateMachine.constraintStateAnimationStarting from version 1.6.0 of ZEPETO.World, transition of Animation played in CharacterStateMachine can be On/Off according to CharacterState of Motion V2.

- true : Turn off ZepetoCharacter.CurrentState, which is affected by controller input, and control the desired animation clip.

👍

Example of using constraintStateAnimation

  • You want your character to use a swimming animation instead of a walking animation. You can apply a swimming animation clip to a new State and fix the State through constraintStateAnimation.
  • If you want to use gesture animation while moving a character, you can apply a gesture animation clip to a new State and move the character with the fixed State using constraintStateAnimation.
  • This can be used when you want to forcibly play a specific animation while temporarily ignoring the parameters values applied to the Animator State.

ZepetoAnimator

UnityEngine Animator functions are available in the form of ZepetoAnimator.

For example, if you want to set an Integer value for a specific Character Animator "State" parameter, you can use:

ZepetoAnimator.SetInteger("State", 1);

For more detailed usage, please refer to the UnityEngine Animator documentation and the sample script below.

📘

UnityEngine Animator

https://docs.unity3d.com/ScriptReference/Animator.html


Example code for controlling ZEPETO Character Animator

An example of animator control of a local player ZEPETO character controlled by the player.

import { Toggle } from 'UnityEngine.UI';
import { SpawnInfo, ZepetoCharacter, ZepetoPlayers } from 'ZEPETO.Character.Controller';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import { WorldService } from 'ZEPETO.World';
import { Animator } from "UnityEngine";
 
export default class SampleScript extends ZepetoScriptBehaviour {
    public testTogle: Toggle;
    private _zepetoCharacter: ZepetoCharacter;
    Start() {
        // Local Player Creation Code (Please delete this section if you are already using local player creation code elsewhere)                        ZepetoPlayers.instance.CreatePlayerWithUserId(WorldService.userId, new SpawnInfo(), true);
 
        // Code for setting the created local player as a ZEPETO character.
          ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
            this._zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character;
 
            // SetInteger Example
            const stateType = Animator.StringToHash("State");
            this._zepetoCharacter.ZepetoAnimator.SetInteger(stateType, 30);
 
            // StateMachine.constraintStateAnimation
            this.testTogle.onValueChanged.AddListener((isActive: bool)=>{
                this._zepetoCharacter.StateMachine.constraintStateAnimation = isActive;
                console.log(isActive);
            });
        });
    }
}

If you run the example, you can see that when the value of StateMachine.constraintStateAnimation is True, the trasition of Animation played in CharacterStateMachine is Off.

If you set the StateMachine.constraintStateAnimation value to False, it will return to its original state.


Controlling CharacterShadow

Starting from version 1.11.3 of ZEPETO.CharacterController Package, an interface has been added to access the ZepetoCharacter Shadow object.

API Specifications:

class CharacterShadow extends UnityEngine.MonoBehaviour {
     
    public target: UnityEngine.Transform;
    public autoSyncTransform: boolean;
                
}

target- Represents the object that serves as the reference for adjusting the transform of the CharacterShadow object.
- By default, the ZEPETO character is set as the target. The transform of the CharacterShadow object is adjusted based on the bottom of the specified character.
autoSyncTransform- A flag value that determines whether to adjust the position of the shadow.
- The default value is true.

With this, you can control the shadow of the Zepeto character at runtime. Below is an example code that uses a toggle to turn the shadow on and off.

import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import { ZepetoCharacter, CharacterShadow, ZepetoPlayer, ZepetoPlayers } from 'ZEPETO.Character.Controller';
import { Toggle } from 'UnityEngine.UI';
 
export default class ShadowController extends ZepetoScriptBehaviour {
 
    public shadowToggle : Toggle;
 
    private _characterShadow : CharacterShadow;
    private _localCharacter: ZepetoCharacter;
     
    Start() {
 
        ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
            this._localCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character;
            this._characterShadow = this._localCharacter.Context.GetComponentInChildren<CharacterShadow>();
            console.log(this._characterShadow.autoSyncTransform);
        });
         
        this.shadowToggle.onValueChanged.AddListener((isActive: bool)=>{
            this._characterShadow.gameObject.SetActive(isActive);
        });
    }
}