--- title: ZEPETO角色 slug: world-sdk-guide-ch/fJx8-zepeto docTags: createdAt: 2024-09-02T08:34:13.135Z --- ZEPETO角色是用于在世界场景中加载的基本ZEPETO角色实例单元。 要控制ZepetoCharacter，请将以下导入语句添加到脚本中。 ```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值。 - 用户ID : 这是一个唯一的ID值，用于区分ZEPETO系统中的用户，并不是在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组件创建的，如下所示。 ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-baJcW2Nc_l3wgSVkNW06M-20240904-102413.gif) ## 控制角色 将通过场景中的角色实例脚本提供一个可以直接控制角色的接口。 | **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() { // 使用 `ZepetoCharacterCreator.CreateByUserId` 创建一个 `ZepetoCharacter`。 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(); } } ``` 如果你运行这个示例，你会看到克隆的角色按以下顺序执行指定的动作。 ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-h1vOH_iqjK4IuRdg62Itn-20240904-102414.gif) :::hint{type="info"} **📘 **请参考以下指南。\[[创建一个NPC](docId\:RLgZcXrMSTkkq6jvTT4L3)] ::: ## 运动状态 与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 中播放的动画过渡可以根据 Motion V2 的 CharacterState 开启/关闭。

- true : 关闭受控制器输入影响的 ZepetoCharacter.CurrentState，并控制所需的动画剪辑。 | :::hint{type="success"} 👍 **使用 constraintStateAnimation 的示例** - 您希望角色使用游泳动画而不是行走动画。您可以将游泳动画剪辑应用于新状态，并通过 constraintStateAnimation 固定该状态。 - 如果您希望在移动角色时使用手势动画，可以将手势动画剪辑应用于新状态，并使用 constraintStateAnimation 通过固定状态移动角色。 - 当您希望强制播放特定动画，同时暂时忽略应用于 Animator 状态的参数值时，可以使用此功能。 ::: ### ZepetoAnimator UnityEngine Animator 函数以 ZepetoAnimator 的形式提供。 例如，如果您想为特定角色动画器的 "状态" 参数设置一个整数值，可以使用： ```typescript ZepetoAnimator.SetInteger("State", 1); ``` 有关更详细的用法，请参考 UnityEngine Animator 文档和下面的示例脚本。 :::hint{type="info"} **📘 UnityEngine Animator** [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() { // 本地玩家创建代码（如果您在其他地方已经使用本地玩家创建代码，请删除此部分） ZepetoPlayers.instance.CreatePlayerWithUserId(WorldService.userId, new SpawnInfo(), true); // 将创建的本地玩家设置为ZEPETO角色的代码。 ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => { this._zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character; // SetInteger 示例 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中播放的动画过渡为Off。 如果您将StateMachine.constraintStateAnimation的值设置为False，它将返回到其原始状态。 ![](https://api.archbee.com/api/optimize/fCt3n1oCa8rgNJ8fw9I2N-kozhM0oDCKDZfQmbmLJy5-20240904-102414.gif) ## 控制角色阴影 从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"}