Studio GuideWorld SDK Guide
Log In

How to apply custom animation

Let's learn how to import external animation files and apply them to ZEPETO characters.

STEP 1 : Setting up animation

Access the site where you want to download animation.
This guide is an example of using the Mixamo site.



Click the desired humanoid animation.


Download the animation and select the "FBX for Unity (.fbx)" option.


Drag and drop the downloaded file to the Unity Project panel.


Click the Rig tab and change the Animation Type to Humanoid.




Without the humanoid setting, it will not be compatible with the ZEPETO character.
Make sure to set it up.

Change the Animation > Motion > Root Motion Node option to <Root Transform> to make your character's animation smoother and more realistic.



Unity Selecting a Root Motion Node

STEP 2 : Setting the animator

Clone an animator object associated with an animator variable in the ZepetoPlayers component inspector.

  • File path : Packages/zepeto.character.controller/Runtime/_Resources/AnimatorController/ZepetoAnimatorV2.controller
  • Drag the animator into the Assets folder.
  • After copying, rename it to ZepetoAnimatorV2_Custom.

Click Hierarchy > ZEPETO > ZepetoPlayers to create it, and drag a copy of the animator you created in the Animation Controller field of the ZepetoPlayers component.


Double-click ZepetoAnimatorV2_Custom to open the animator tab.

  • Drag and drop the new animation into the animator to create an animation state.
  • Right-click the animation state you created, and then click Make Transition to create a transition that returns to the Idle state.

STEP 3 : Example of using a custom animation file

Let's create an example of how to play an animation when you click a button.


STEP 3-1 : Setting the UI

  • Add Hierachy > UI > Button.

Example Button

STEP 3-2 : Writing a script

  1. Create a Hierarchy > Create Empty Object and rename it to CharacterController.
  2. Create Project > Create > ZEPETO > TypeScript and rename it to CharacterController.
  3. Write a sample script as follows:
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { Button } from 'UnityEngine.UI';
import { Animator, AnimationClip } from 'UnityEngine';
import { SpawnInfo, ZepetoPlayers, LocalPlayer, ZepetoCharacter } from 'ZEPETO.Character.Controller';
import { WorldService } from 'ZEPETO.World';

export default class CharacterController extends ZepetoScriptBehaviour {

    public customAnimationClip: AnimationClip;
    public playCustomAnimationButton: Button;
    private _localPlayerAnimator: Animator;

    Start() {
        this.playCustomAnimationButton.onClick.AddListener(() => {

        ZepetoPlayers.instance.CreatePlayerWithUserId(WorldService.userId, new SpawnInfo(), true);

        ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
            const player: LocalPlayer = ZepetoPlayers.instance.LocalPlayer;
            this._localPlayerAnimator = player.zepetoPlayer.character.GetComponentInChildren<Animator>();



  • The flow of the script is as follows:
    • Start()
      • Adds a listener to playCustomAnimationButton that play animation when clicked.
      • Calls the ZepetoPlayers.instance.CreatePlayerWithUserId() function to create a local player.
      • Get the animator component of the local player and stores it in the localPlayerAnimator variable.
  1. Attach the CharacterController script to the CharacterController object.
  2. Assign Custom Animation Clip, Play Custom Animation Button from the inspector.
    • Assign an animation clip that is set to Custom Animation Clip.
    • Drag and assign the button to the Play Custom Animation Button.

Example script setting screen

  1. Play and click the button to play the animation.


If you use a custom character other than a ZEPETO character,
you can apply the ZEPETO animation if it is a humanoid character.