Personnage ZEPETO

17 min

ZEPETOCharacter est l'unité de base de l'instance de personnage ZEPETO pour le chargement dans une scène mondiale.

Pour contrôler le ZepetoCharacter, ajoutez la déclaration d'importation suivante au script.

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

API ZepetoCharacter

Cette API crée et supprime des instances de personnages ZEPETO, y compris les composants de contrôleur d'animateur et de contrôleur de personnage.

API	Description
CreateByZepetoId(zepetoId: string, spawnInfo: SpawnInfo, complete: System.Action$1)	Utilisez un ID ZEPETO pour générer une instance de personnage ZEPETO. Principalement utilisé pour la création de personnages NPC.
CreateByUserId(userId: string, spawnInfo: SpawnInfo, complete: System.Action$1)	Créez une instance de personnage ZEPETO avec UserId. Principalement utilisé pour la création de personnages NPC.
RemoveCharacter(character: ZepetoCharacter)	Supprimez l'instance de personnage.

Cette API crée des instances de modèle de personnage ZEPETO, à l'exclusion des composants de contrôleur d'animateur et de contrôleur de personnage.

ZEPETO ID : C'est la valeur d'ID que l'utilisateur spécifie directement et utilise dans l'application ZEPETO.
User ID : C'est une valeur d'ID unique qui distingue les utilisateurs au sein du système ZEPETO, et ce n'est pas une valeur exposée sur l'interface utilisateur. Vous pouvez le vérifier à l'aide d'un script.

Si vous êtes intéressé par l'API ZepetoCharacter, consultez la documentation :

Veuillez vous référer au guide suivant. [API ZEPETO.Character.Controller]

Créer/Supprimer un personnage

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() {
        // Créer une nouvelle instance de la classe SpawnInfo
        const firstCloneSpawnInfo = new SpawnInfo();
        firstCloneSpawnInfo.position = new Vector3(0,0,1);
 
        const secondCloneSpawnInfo = new SpawnInfo();
        secondCloneSpawnInfo.position = new Vector3(0,0,3);
 
 
 
        // Créer un `ZepetoCharacter` en utilisant ZepetoId
        ZepetoCharacterCreator.CreateByZepetoId(this.zepetoId, firstCloneSpawnInfo, (character: ZepetoCharacter) => {
            this._cloneCharacter = character;
        });
 
 
        // Créer un `ZepetoCharacterModel` en utilisant ZepetoId
        ZepetoCharacterCreator.CreateModelByZepetoId(this.zepetoId, secondCloneSpawnInfo, (object) => {
            this._cloneCharacterModel = object;
        });
 
        // Créer un `ZepetoCharacter` en utilisant UserId
        /*
        ZepetoCharacterCreator.CreateByUserId(WorldService.userId, new SpawnInfo(), (character: ZepetoCharacter) => {
            this._cloneCharacter = character;
        })
  
        // Créer un `ZepetoCharacterModel` en utilisant UserId
        ZepetoCharacterCreator.CreateModelByUserId(WorldService.userId, new SpawnInfo(), (object) => {
            this._cloneCharacterModel = object;
        })
        */
 
        // Configurer un événement de clic pour le `removeCloneCharacterButton` pour supprimer le personnage cloné.
        this.removeCloneCharacterButton.onClick.AddListener(() => {
            ZepetoCharacterCreator.RemoveCharacter(this._cloneCharacter);
        });
 
        // Configurer un événement de clic pour le `removeCloneCharacterModelButton` pour détruire le modèle de personnage cloné.
        this.removeCloneCharacterModelButton.onClick.AddListener(() => {
            Object.Destroy(this._cloneCharacterModel);
        });
    }
 
}

Si vous exécutez l'exemple, vous pouvez voir que le CharacterModel à gauche est créé sans les composants Animator Controller et Character Controller comme indiqué ci-dessous.

Contrôler le personnage

Une interface où vous pouvez contrôler directement le personnage sera fournie par le script d'une instance de personnage dans une scène.

API	Description
MoveToPosition(position : Vector3)	Déplace le personnage à la position.
MoveContinuously(direction : Vector3)	Déplace continuellement (mise à jour) dans la direction où le personnage regarde.
MoveContinuously(direction : Vector2)	Déplace continuellement (mise à jour) dans la direction où le personnage regarde.
StopMoving()	Empêche le personnage de se déplacer.
Jump()	Le personnage saute à la puissance de saut définie.
DoubleJump()	Le personnage effectue un double saut avec la puissance de double saut actuellement définie. (Applicable uniquement lors de l'utilisation de MotionController V2)
Teleport(position: UnityEngine.Vector3, rotation: UnityEngine.Quaternion)	Le personnage se déplace instantanément vers la transformation.
SetGesture(gesture: UnityEngine.AnimationClip)	Pour le AnimationClip spécifié, le mouvement du personnage est joué. Pendant que SetGesture est en cours, les entrées de contrôle de l'utilisateur ne sont pas appliquées au personnage. Lorsque l'option de boucle de AnimationClip est activée, elle continue à jouer jusqu'à ce que CancelGesture() soit appelé.
CancelGesture()	Arrête la lecture de l'Animation Clip actuellement en cours via SetGesture(). Lorsque CancelGesture() est exécuté, l'entrée de contrôle de l'utilisateur est à nouveau appliquée au contrôle du personnage.

Exemple de code de caractère de contrôle.

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() {
 
        // Créer un `ZepetoCharacter` en utilisant `ZepetoCharacterCreator.CreateByUserId`.
        ZepetoCharacterCreator.CreateByUserId(WorldService.userId, new SpawnInfo(), (character: ZepetoCharacter) => {
            // Assigner le personnage créé à `_cloneCharacter`.
            this._cloneCharacter = character;
 
            // Exécuter `ActionCoroutine()` en tant que coroutine.
            this.StartCoroutine(this.ActionCoroutine());
        })
    }
 
    *ActionCoroutine() {
 
        yield new WaitForSeconds(3);
 
        // Déplacer `_cloneCharacter` vers `targetPosition` après avoir attendu 3 secondes.
        this._cloneCharacter.MoveToPosition(this.targetPosition);
 
        yield new WaitForSeconds(1);
 
        // Faire sauter `_cloneCharacter` après avoir attendu 1 seconde.
        this._cloneCharacter.Jump();
 
        yield new WaitForSeconds(1);
 
        // Définir le geste de `_cloneCharacter` sur `danceGesture` après avoir attendu 1 seconde.
        this._cloneCharacter.SetGesture(this.danceGesture);
 
        yield new WaitForSeconds(3);
 
        // Annuler le geste de `_cloneCharacter` après avoir attendu 3 secondes.
        this._cloneCharacter.CancelGesture();
    }
 
}

Si vous exécutez l'exemple, vous pouvez voir que le personnage cloné effectue les actions spécifiées dans l'ordre comme suit.

📘 Veuillez vous référer au guide suivant. [Créer et contrôler des PNJ]

État de mouvement

L'API liée à l'état de mouvement du personnage ZEPETO est la suivante :

API	Description
motionState.useDoubleJump = (boolean);	Définir si le personnage peut utiliser le DoubleJump.
motionState.doubleJumpPower = (number);	Définir la puissance du DoubleJump du personnage.
motionState.useLandingRoll = (boolean);	Définir si le personnage utilise le LandingRoll.
motionState.landingRollSpeed = (number);	Définir la valeur de vitesse du LandingRoll du personnage.
motionState.useMoveTurn = (boolean);	Définir si le personnage utilise MoveTurn.
motionState.Gravity = (number);	Définir la valeur de gravité du personnage.
motionState.CurrentJumpState	Vous pouvez vérifier l'état actuel de saut du personnage. - Aucun = -1, JumpIdle = 0, JumpMove = 1, JumpDash = 2, JumpDouble = 3
motionState.CurrentLandingState	Vous pouvez vérifier l'état actuel d'atterrissage du personnage. - Aucun = -1, LandingSlight = 0, LandingDeep = 1, LandingRoll = 2
motionState.CurrentMoveState	Vous pouvez vérifier l'état actuel de mouvement de votre personnage. - Aucun = -1, MoveWalk = 0, MoveRun = 1

Exemple de code d'état de mouvement

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) => {
            // Assigner le personnage créé à `_cloneCharacter`.
            this._cloneCharacter = character;
 
            // Définir diverses propriétés de `motionState` dans `_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() {
        // Vérifier si `_cloneCharacter` n'est pas nul.
        if (this._cloneCharacter != null) {
            // Afficher l'état de saut actuel de `motionState` dans `_cloneCharacter`.
            console.log(`État de saut actuel : ${this._cloneCharacter.motionState.currentJumpState}`);
 
            // Afficher l'état d'atterrissage actuel de `motionState` dans `_cloneCharacter`.
            console.log(`État d'atterrissage actuel : ${this._cloneCharacter.motionState.currentLandingState}`);
 
            // Afficher l'état de mouvement actuel de `motionState` dans `_cloneCharacter`.
            console.log(`État de mouvement actuel : ${this._cloneCharacter.motionState.currentMoveState}`);
        }
    }
}

Contrôler l'animateur de personnage ZEPETO

API pour contrôler l'animateur de personnage ZEPETO

API	Description
StateMachine.constraintStateAnimation	À partir de la version 1.6.0 de ZEPETO.World, la transition de l'animation jouée dans CharacterStateMachine peut être activée/désactivée selon l'état de mouvement de CharacterState V2. - vrai : Désactiver ZepetoCharacter.CurrentState, qui est affecté par l'entrée du contrôleur, et contrôler le clip d'animation souhaité.

👍 Exemple d'utilisation de constraintStateAnimation

Vous voulez que votre personnage utilise une animation de natation au lieu d'une animation de marche. Vous pouvez appliquer un clip d'animation de natation à un nouvel état et fixer l'état via constraintStateAnimation.
Si vous souhaitez utiliser une animation de geste tout en déplaçant un personnage, vous pouvez appliquer un clip d'animation de geste à un nouvel état et déplacer le personnage avec l'état fixé en utilisant constraintStateAnimation.
Cela peut être utilisé lorsque vous souhaitez jouer de force une animation spécifique tout en ignorant temporairement les valeurs des paramètres appliqués à l'état de l'animateur.

ZepetoAnimator

Les fonctions Animator de UnityEngine sont disponibles sous la forme de ZepetoAnimator.

Par exemple, si vous souhaitez définir une valeur entière pour un paramètre "État" spécifique de l'Animator de personnage, vous pouvez utiliser :

ZepetoAnimator.SetInteger("State", 1);

Pour une utilisation plus détaillée, veuillez vous référer à la documentation de l'Animator de UnityEngine et au script d'exemple ci-dessous.

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

Exemple de code pour contrôler l'Animator de personnage ZEPETO

Un exemple de contrôle de l'Animator d'un personnage ZEPETO local contrôlé par le joueur.

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);
            });
        });
    }
}

Si vous exécutez l'exemple, vous pouvez voir que lorsque la valeur de StateMachine.constraintStateAnimation est True, la transition de l'Animation jouée dans CharacterStateMachine est Off.

Si vous définissez la valeur de StateMachine.constraintStateAnimation sur False, elle reviendra à son état d'origine.

Contrôler CharacterShadow

À partir de la version 1.11.3 du package ZEPETO.CharacterController, une interface a été ajoutée pour accéder à l'objet ZepetoCharacter Shadow.

Spécifications de l'API :

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

cible	- Représente l'objet qui sert de référence pour ajuster la transformation de l'objet CharacterShadow. - Par défaut, le personnage ZEPETO est défini comme la cible. La transformation de l'objet CharacterShadow est ajustée en fonction du bas du personnage spécifié.
autoSyncTransform	- Une valeur de drapeau qui détermine si la position de l'ombre doit être ajustée. - La valeur par défaut est vraie.

Avec cela, vous pouvez contrôler l'ombre du personnage Zepeto à l'exécution. Ci-dessous se trouve un exemple de code qui utilise un interrupteur pour activer et désactiver l'ombre.

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);
        });
    }
}