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値です。
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)	キャラクターがTransformに瞬時に移動します。
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に応じてOn/Offできます。 - true : コントローラー入力の影響を受けるZepetoCharacter.CurrentStateをオフにし、希望するアニメーションクリップを制御します。

👍 constraintStateAnimationの使用例

キャラクターに歩行アニメーションの代わりに水泳アニメーションを使用させたい場合は、水泳アニメーションクリップを新しいステートに適用し、constraintStateAnimationを通じてそのステートを固定できます。
キャラクターを移動させながらジェスチャーアニメーションを使用したい場合は、ジェスチャーアニメーションクリップを新しいステートに適用し、constraintStateAnimationを使用して固定されたステートでキャラクターを移動させることができます。
これは、Animator Stateに適用されたパラメータ値を一時的に無視しながら特定のアニメーションを強制的に再生したい場合に使用できます。

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で再生されるアニメーションの遷移がオフになるのがわかります。

StateMachine.constraintStateAnimationの値をFalseに設定すると、元の状態に戻ります。

キャラクターシャドウの制御

ZEPETO.CharacterControllerパッケージのバージョン1.11.3から、ZepetoCharacter Shadowオブジェクトにアクセスするためのインターフェースが追加されました。

API仕様：

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

ターゲット	- 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);
        });
    }
}