ZEPETO Character

16 분

ZEPETOCharacter는 월드 씬에 로드하기 위한 기본 ZEPETO 캐릭터 인스턴스 단위입니다.

ZepetoCharacter를 제어하려면 스크립트에 다음 import 문을 추가하세요.

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

ZepetoCharacter API

이 API는 애니메이터 컨트롤러 및 캐릭터 컨트롤러 구성 요소를 포함하여 ZEPETO 캐릭터 인스턴스를 생성하고 제거합니다.

API	설명
CreateByZepetoId(zepetoId: string, spawnInfo: SpawnInfo, complete: System.Action$1)	ZEPETO ID를 사용하여 ZEPETO 캐릭터 인스턴스를 생성합니다. 주로 NPC 캐릭터 생성을 위해 사용됩니다.
CreateByUserId(userId: string, spawnInfo: SpawnInfo, complete: System.Action$1)	UserId로 ZEPETO 캐릭터 인스턴스를 생성합니다. 주로 NPC 캐릭터 생성을 위해 사용됩니다.
RemoveCharacter(character: ZepetoCharacter)	캐릭터 인스턴스를 삭제합니다.

이 API는 애니메이터 컨트롤러 및 캐릭터 컨트롤러 구성 요소를 제외한 ZEPETO 캐릭터 모델 인스턴스를 생성합니다.

ZEPETO ID : 사용자가 직접 지정하고 ZEPETO 앱 내에서 사용하는 ID 값입니다.
User ID : ZEPETO 시스템 내에서 사용자를 구별하는 고유 ID 값이며, UI에 노출되지 않는 값입니다. 스크립트를 사용하여 확인할 수 있습니다.

ZepetoCharacter API에 관심이 있으시면 문서를 참조하세요:

다음 가이드를 참조하세요. [ZEPETO.Character.Controller API]

캐릭터 생성/삭제

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() {
        // SpawnInfo 클래스의 새 인스턴스 생성
        const firstCloneSpawnInfo = new SpawnInfo();
        firstCloneSpawnInfo.position = new Vector3(0,0,1);
 
        const secondCloneSpawnInfo = new SpawnInfo();
        secondCloneSpawnInfo.position = new Vector3(0,0,3);
 
 
 
        // ZepetoId를 사용하여 `ZepetoCharacter` 생성
        ZepetoCharacterCreator.CreateByZepetoId(this.zepetoId, firstCloneSpawnInfo, (character: ZepetoCharacter) => {
            this._cloneCharacter = character;
        });
 
 
        // ZepetoId를 사용하여 `ZepetoCharacterModel` 생성
        ZepetoCharacterCreator.CreateModelByZepetoId(this.zepetoId, secondCloneSpawnInfo, (object) => {
            this._cloneCharacterModel = object;
        });
 
        // UserId를 사용하여 `ZepetoCharacter` 생성
        /*
        ZepetoCharacterCreator.CreateByUserId(WorldService.userId, new SpawnInfo(), (character: ZepetoCharacter) => {
            this._cloneCharacter = character;
        })
  
        // UserId를 사용하여 `ZepetoCharacterModel` 생성
        ZepetoCharacterCreator.CreateModelByUserId(WorldService.userId, new SpawnInfo(), (object) => {
            this._cloneCharacterModel = object;
        })
        */
 
        // `removeCloneCharacterButton`의 클릭 이벤트 설정하여 클론 캐릭터 제거.
        this.removeCloneCharacterButton.onClick.AddListener(() => {
            ZepetoCharacterCreator.RemoveCharacter(this._cloneCharacter);
        });
 
        // `removeCloneCharacterModelButton`의 클릭 이벤트 설정하여 클론 캐릭터 모델 파괴.
        this.removeCloneCharacterModelButton.onClick.AddListener(() => {
            Object.Destroy(this._cloneCharacterModel);
        });
    }
 
}

예제를 실행하면 왼쪽의 CharacterModel이 아래와 같이 Animator Controller 및 Character Controller 구성 요소 없이 생성되는 것을 볼 수 있습니다.

캐릭터 제어

장면의 캐릭터 인스턴스에서 스크립트를 통해 캐릭터를 직접 제어할 수 있는 인터페이스가 제공됩니다.

API	설명
MoveToPosition(position : Vector3)	캐릭터를 위치로 이동시킵니다.
MoveContinuously(direction : Vector3)	캐릭터가 바라보는 방향으로 지속적으로 이동합니다. (업데이트)
MoveContinuously(direction : Vector2)	캐릭터가 바라보는 방향으로 지속적으로 이동합니다. (업데이트)
StopMoving()	캐릭터의 이동을 멈춥니다.
Jump()	캐릭터가 설정된 점프 파워로 점프합니다.
DoubleJump()	캐릭터가 현재 설정된 더블 점프 파워로 더블 점프합니다. (MotionController V2 사용 시에만 적용)
Teleport(position: UnityEngine.Vector3, rotation: UnityEngine.Quaternion)	캐릭터가 즉시 변환합니다.
SetGesture(gesture: UnityEngine.AnimationClip)	지정된 AnimationClip에 대해 캐릭터의 동작이 재생됩니다. SetGesture가 실행되는 동안 사용자의 제어 입력은 캐릭터에 적용되지 않습니다. AnimationClip의 루프 옵션이 켜져 있으면 CancelGesture()가 호출될 때까지 계속 재생됩니다.
CancelGesture()	SetGesture()를 통해 현재 재생 중인 Animation Clip의 재생을 중지합니다. CancelGesture()가 실행되면 사용자의 제어 입력이 다시 캐릭터 제어에 적용됩니다.

제어 문자 예제 코드입니다.

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() {
 
        // `ZepetoCharacter`를 `ZepetoCharacterCreator.CreateByUserId`를 사용하여 생성합니다.
        ZepetoCharacterCreator.CreateByUserId(WorldService.userId, new SpawnInfo(), (character: ZepetoCharacter) => {
            // 생성된 캐릭터를 `_cloneCharacter`에 할당합니다.
            this._cloneCharacter = character;
 
            // `ActionCoroutine()`을 코루틴으로 실행합니다.
            this.StartCoroutine(this.ActionCoroutine());
        })
    }
 
    *ActionCoroutine() {
 
        yield new WaitForSeconds(3);
 
        // 3초 대기 후 `_cloneCharacter`를 `targetPosition`으로 이동시킵니다.
        this._cloneCharacter.MoveToPosition(this.targetPosition);
 
        yield new WaitForSeconds(1);
 
        // 1초 대기 후 `_cloneCharacter`가 점프하게 합니다.
        this._cloneCharacter.Jump();
 
        yield new WaitForSeconds(1);
 
        // 1초 대기 후 `_cloneCharacter`의 제스처를 `danceGesture`로 설정합니다.
        this._cloneCharacter.SetGesture(this.danceGesture);
 
        yield new WaitForSeconds(3);
 
        // 3초 대기 후 `_cloneCharacter`의 제스처를 취소합니다.
        this._cloneCharacter.CancelGesture();
    }
 
}

예제를 실행하면 복제된 캐릭터가 다음과 같이 지정된 작업을 순서대로 수행하는 것을 볼 수 있습니다.

📘 다음 가이드를 참조하십시오. [NPC 생성하고 제어하기]

모션 상태

ZEPETO 캐릭터의 모션 상태와 관련된 API는 다음과 같습니다:

API	설명
motionState.useDoubleJump = (boolean);	캐릭터가 더블 점프를 사용할 수 있는지 설정합니다.
motionState.doubleJumpPower = (number);	캐릭터의 더블 점프 파워를 설정합니다.
motionState.useLandingRoll = (boolean);	캐릭터의 착지 롤을 사용할지 설정합니다.
motionState.landingRollSpeed = (number);	캐릭터의 착지 롤 속도 값을 설정합니다.
motionState.useMoveTurn = (boolean);	캐릭터의 이동 회전을 사용할지 설정합니다.
motionState.Gravity = (number);	캐릭터의 중력 값을 설정합니다.
motionState.CurrentJumpState	캐릭터의 현재 점프 상태를 확인할 수 있습니다. - 없음 = -1, 점프 대기 = 0, 점프 이동 = 1, 점프 대시 = 2, 점프 더블 = 3
motionState.CurrentLandingState	캐릭터의 현재 착지 상태를 확인할 수 있습니다. - 없음 = -1, 착지 약간 = 0, 착지 깊게 = 1, 착지 롤 = 2
motionState.CurrentMoveState	캐릭터의 현재 이동 상태를 확인할 수 있습니다. - 없음 = -1, 이동 걷기 = 0, 이동 달리기 = 1

모션 상태 예제 코드

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) => {
            // 생성된 캐릭터를 `_cloneCharacter`에 할당합니다.
            this._cloneCharacter = character;
 
            // `_cloneCharacter`의 `motionState`의 다양한 속성을 설정합니다.
            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() {
        // `_cloneCharacter`가 null이 아닌지 확인합니다.
        if (this._cloneCharacter != null) {
            // `_cloneCharacter`의 `motionState`의 현재 점프 상태를 출력합니다.
            console.log(`현재 점프 상태: ${this._cloneCharacter.motionState.currentJumpState}`);
 
            // `_cloneCharacter`의 `motionState`의 현재 착륙 상태를 출력합니다.
            console.log(`현재 착륙 상태: ${this._cloneCharacter.motionState.currentLandingState}`);
 
            // `_cloneCharacter`의 `motionState`의 현재 이동 상태를 출력합니다.
            console.log(`현재 이동 상태: ${this._cloneCharacter.motionState.currentMoveState}`);
        }
    }
}

ZEPETO 캐릭터 애니메이터 제어하기

ZEPETO 캐릭터 애니메이터를 제어하기 위한 API

API	설명
StateMachine.constraintStateAnimation	ZEPETO.World의 1.6.0 버전부터, CharacterStateMachine에서 재생되는 Animation의 전환은 Motion V2의 CharacterState에 따라 On/Off할 수 있습니다. - true : 컨트롤러 입력에 영향을 받는 ZepetoCharacter.CurrentState를 끄고 원하는 애니메이션 클립을 제어합니다.

👍 constraintStateAnimation 사용 예시

캐릭터가 걷는 애니메이션 대신 수영 애니메이션을 사용하도록 하려면, 수영 애니메이션 클립을 새로운 상태에 적용하고 constraintStateAnimation을 통해 상태를 고정할 수 있습니다.
캐릭터를 이동시키는 동안 제스처 애니메이션을 사용하고 싶다면, 제스처 애니메이션 클립을 새로운 상태에 적용하고 constraintStateAnimation을 사용하여 고정된 상태로 캐릭터를 이동시킬 수 있습니다.
이것은 Animator State에 적용된 매개변수 값을 일시적으로 무시하면서 특정 애니메이션을 강제로 재생하고 싶을 때 사용할 수 있습니다.

ZepetoAnimator

유니티엔진 애니메이터 기능은 ZepetoAnimator 형태로 제공됩니다.

예를 들어, 특정 캐릭터 애니메이터 "상태" 매개변수에 정수 값을 설정하려면 다음을 사용할 수 있습니다.

ZepetoAnimator.SetInteger("State", 1);

자세한 사용법은 유니티엔진 애니메이터 문서와 아래 샘플 스크립트를 참조하십시오.

📘 유니티엔진 애니메이터 https://docs.unity3d.com/ScriptReference/Animator.html

ZEPETO 캐릭터 애니메이터 제어를 위한 예제 코드

플레이어가 제어하는 로컬 플레이어 ZEPETO 캐릭터의 애니메이터 제어 예제입니다.

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

예제를 실행하면 StateMachine.constraintStateAnimation의 값이 True일 때 CharacterStateMachine에서 재생되는 Animation의 전환이 꺼진 것을 볼 수 있습니다.

StateMachine.constraintStateAnimation 값을 False로 설정하면 원래 상태로 돌아갑니다.

CharacterShadow 제어하기

ZEPETO.CharacterController 패키지의 1.11.3 버전부터 ZepetoCharacter Shadow 객체에 접근할 수 있는 인터페이스가 추가되었습니다.

API 사양:

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

target	- CharacterShadow 객체의 변환을 조정하기 위한 참조 역할을 하는 객체입니다. - 기본적으로 ZEPETO 캐릭터가 대상입니다. 지정된 캐릭터의 바닥을 기준으로 CharacterShadow 객체의 변환이 조정됩니다.
autoSyncTransform	- 그림자의 위치를 조정할지 여부를 결정하는 플래그 값입니다. - 기본값은 true입니다.

이를 통해 런타임에서 Zepeto 캐릭터의 그림자를 제어할 수 있습니다. 아래는 그림자를 켜고 끄는 토글을 사용하는 예제 코드입니다.

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