---
title: ZEPETO Character
slug: world-sdk-guide-kr/zepeto-character
docTags:
createdAt: 2024-09-02T08:34:13.135Z
---
ZEPETOCharacter는 월드 씬에 로드하기 위한 기본 ZEPETO 캐릭터 인스턴스 단위입니다.
ZepetoCharacter를 제어하려면 스크립트에 다음 import 문을 추가하세요.
```typescript
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 캐릭터 모델 인스턴스를 생성합니다.
:::hint{type="success"}
- ZEPETO ID : 사용자가 직접 지정하고 ZEPETO 앱 내에서 사용하는 ID 값입니다.
- User ID : ZEPETO 시스템 내에서 사용자를 구별하는 고유 ID 값이며, UI에 노출되지 않는 값입니다. 스크립트를 사용하여 확인할 수 있습니다.
:::
ZepetoCharacter API에 관심이 있으시면 문서를 참조하세요:
:::hint{type="info"}
- 다음 가이드를 참조하세요. \[[ZEPETO.Character.Controller API](https://developer.zepeto.me/docs/character-controller/)]
:::
## 캐릭터 생성/삭제
```typescript
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()가 실행되면 사용자의 제어 입력이 다시 캐릭터 제어에 적용됩니다. |
### 제어 문자 예제 코드입니다.
```typescript
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();
}
}
```
예제를 실행하면 복제된 캐릭터가 다음과 같이 지정된 작업을 순서대로 수행하는 것을 볼 수 있습니다.
:::hint{type="info"}
**📘 **다음 가이드를 참조하십시오. \[[NPC 생성하고 제어하기](docId\:j8jEa_lYkIzfWb6vpC1wx)]
:::
## 모션 상태
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 |
### 모션 상태 예제 코드
```typescript
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를 끄고 원하는 애니메이션 클립을 제어합니다. |
:::hint{type="success"}
👍 **constraintStateAnimation 사용 예시**
- 캐릭터가 걷는 애니메이션 대신 수영 애니메이션을 사용하도록 하려면, 수영 애니메이션 클립을 새로운 상태에 적용하고 constraintStateAnimation을 통해 상태를 고정할 수 있습니다.
- 캐릭터를 이동시키는 동안 제스처 애니메이션을 사용하고 싶다면, 제스처 애니메이션 클립을 새로운 상태에 적용하고 constraintStateAnimation을 사용하여 고정된 상태로 캐릭터를 이동시킬 수 있습니다.
- 이것은 Animator State에 적용된 매개변수 값을 일시적으로 무시하면서 특정 애니메이션을 강제로 재생하고 싶을 때 사용할 수 있습니다.
:::
### ZepetoAnimator
유니티엔진 애니메이터 기능은 ZepetoAnimator 형태로 제공됩니다.
예를 들어, 특정 캐릭터 애니메이터 "상태" 매개변수에 정수 값을 설정하려면 다음을 사용할 수 있습니다.
```typescript
ZepetoAnimator.SetInteger("State", 1);
```
자세한 사용법은 유니티엔진 애니메이터 문서와 아래 샘플 스크립트를 참조하십시오.
:::hint{type="info"}
**📘 유니티엔진 애니메이터**
[https://docs.unity3d.com/ScriptReference/Animator.html](https://docs.unity3d.com/ScriptReference/Animator.html)
:::
### ZEPETO 캐릭터 애니메이터 제어를 위한 예제 코드
플레이어가 제어하는 로컬 플레이어 ZEPETO 캐릭터의 애니메이터 제어 예제입니다.
```typescript
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 사양:
:::CodeblockTabs
CharacterShadow 구성 요소 인터페이스
```typescript
class CharacterShadow extends UnityEngine.MonoBehaviour {
public target: UnityEngine.Transform;
public autoSyncTransform: boolean;
}
```
:::
| target | - CharacterShadow 객체의 변환을 조정하기 위한 참조 역할을 하는 객체입니다.
- 기본적으로 ZEPETO 캐릭터가 대상입니다. 지정된 캐릭터의 바닥을 기준으로 CharacterShadow 객체의 변환이 조정됩니다. |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| autoSyncTransform | - 그림자의 위치를 조정할지 여부를 결정하는 플래그 값입니다.
- 기본값은 true입니다. |
이를 통해 런타임에서 Zepeto 캐릭터의 그림자를 제어할 수 있습니다. 아래는 그림자를 켜고 끄는 토글을 사용하는 예제 코드입니다.
```typescript
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();
console.log(this._characterShadow.autoSyncTransform);
});
this.shadowToggle.onValueChanged.AddListener((isActive: bool)=>{
this._characterShadow.gameObject.SetActive(isActive);
});
}
}
```
::Image[]{src="https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-64hnCm9hLy9fuqdNyzg7y-20240904-102414.gif" size="92" width="600" height="326" position="center" showCaption="false"}