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.
API | Description |
---|---|
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.
API | Description |
---|---|
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:
- Please refer to the following guide. [ZEPETO.Character.Controller API]
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.
API | Description |
---|---|
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:
API | Description |
---|---|
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.CurrentJumpState | You can check the character's current jumping state. - None = -1, JumpIdle = 0, JumpMove = 1, JumpDash = 2, JumpDouble = 3 |
motionState.CurrentLandingState | You can check the character's current landing status. - None = -1, LandingSlight = 0, LandingDeep = 1, LandingRoll = 2 |
motionState.CurrentMoveState | You 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
API | Description |
---|---|
StateMachine.constraintStateAnimation | Starting 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
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);
});
}
}