ZEPETO角色

16 分

ZEPETO角色是用于在世界场景中加载的基本ZEPETO角色实例单元。

要控制ZepetoCharacter，请将以下导入语句添加到脚本中。

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值。
用户ID : 这是一个唯一的ID值，用于区分ZEPETO系统中的用户，并不是在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() {
 
        // 使用 `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();
    }
 
}

如果你运行这个示例，你会看到克隆的角色按以下顺序执行指定的动作。

📘 请参考以下指南。[创建一个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 中播放的动画过渡可以根据 Motion V2 的 CharacterState 开启/关闭。 - true : 关闭受控制器输入影响的 ZepetoCharacter.CurrentState，并控制所需的动画剪辑。

👍 使用 constraintStateAnimation 的示例

您希望角色使用游泳动画而不是行走动画。您可以将游泳动画剪辑应用于新状态，并通过 constraintStateAnimation 固定该状态。
如果您希望在移动角色时使用手势动画，可以将手势动画剪辑应用于新状态，并使用 constraintStateAnimation 通过固定状态移动角色。
当您希望强制播放特定动画，同时暂时忽略应用于 Animator 状态的参数值时，可以使用此功能。

ZepetoAnimator

UnityEngine Animator 函数以 ZepetoAnimator 的形式提供。

例如，如果您想为特定角色动画器的 "状态" 参数设置一个整数值，可以使用：

ZepetoAnimator.SetInteger("State", 1);

有关更详细的用法，请参考 UnityEngine Animator 文档和下面的示例脚本。

📘 UnityEngine Animator 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() {
        // 本地玩家创建代码（如果您在其他地方已经使用本地玩家创建代码，请删除此部分）                        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，它将返回到其原始状态。

控制角色阴影

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