プレイヤーを外部から操作するためのハンドルです。 プレイヤーのアバターを変更してもPlayerHandleは不変です。 ユーザーは入室ごとに別のプレイヤーとして取り扱われます。 このため、再入室したユーザーに対しては再度PlayerHandleを取得しなおす必要があります。

イベントでは、ゴーストやグループビューイングの参加者はスクリプトから取得できません。 詳細はドキュメントを参照してください。

Hierarchy

  • PlayerHandle

Properties

id: string

空間内のプレイヤーを一意に表すIDの文字列表現です。 idが等しいPlayerHandleは同一のプレイヤーを指し示します。 この値は同じユーザーでも入室ごとに異なります。

idfc: null | string

IDFCの値を取得します。 IDFCはクリエイターがユーザーを一意に認識するために利用できる文字列です。 この文字列は32文字で、使われる文字は 0123456789abcdef です。 この文字列はそのアイテム・ワールドをアップロードしたアカウントとユーザーのアカウントとの組によって決定されます。ユーザーの使用するデバイスやスペースによっては変化しません。 プレイヤーが存在しないとき、nullを返します。プレイヤーの存在はexistsで確認できます。

この文字列はコンテンツ体験を向上する目的で利用できます。当社が不適切と判断した場合、予告なく利用を制限させていただく場合もあります。

type: "player"

文字列 "player" を返します。 この値は ItemHandlePlayerHandle を区別するために利用できます。

userDisplayName: null | string

プレイヤーの表示名です。 ユーザーは自分の表示名を変更することができ、異なるユーザーが同じ表示名を使うことができます。 プレイヤーが存在しないとき、nullを返します。プレイヤーの存在はexistsで確認できます。

userId: null | string

プレイヤーのユーザーIDです。 ユーザーは自分のユーザーIDを変更することができますが、 異なるユーザーが同じユーザーIDを同時にもつことはありません。 プレイヤーが存在しないとき、nullを返します。プレイヤーの存在はexistsで確認できます。

Methods

  • Beta

    プレイヤーに速度を加えます。 プレイヤーの最終的な移動速度は、加えられた速度とプレイヤー入力の両方から決定されます。 プレイヤーが地面に接している間、加えられた速度は摩擦と似たような原理で減速し続けます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    • velocity: Vector3

      加えられる速度 (グローバル座標)

    Returns void

  • プレイヤーが入室中ならtrueを返し、退室済みならfalseを返します。 プレイヤーが通信の不具合などで一時的に非表示になっている場合もtrueを返します。

    Returns boolean

  • イベントにおけるプレイヤーのロールを取得します。 プレイヤーの存在する空間がイベントではない場合はnullを返します。 プレイヤーが入場した直後はnullを返すことがあります。

    プレイヤーが存在しないとき、nullを返します。プレイヤーの存在はexistsで確認できます。

    Returns

    プレイヤーのイベントのロール

    Returns null | EventRole

  • Beta

    プレイヤーのヒューマノイドボーンの位置を取得します。 値はグローバル座標です。 アバターのロードが完了していない場合や、アバターにボーンが存在しない場合はnullが返されます。

    Parameters

    Returns null | Vector3

  • Beta

    プレイヤーのヒューマノイドボーンの回転を取得します。 値はグローバル座標です。 アバターのロードが完了していない場合や、アバターにボーンが存在しない場合はnullが返されます。

    Parameters

    Returns null | Quaternion

  • プレイヤーの位置(グローバル座標)を取得します。取得に失敗したときはnullを返します。

    Returns null | Vector3

  • プレイヤーの向き(グローバル座標)を取得します。取得に失敗したときはnullを返します。

    Returns null | Quaternion

  • プレイヤーにワールド内商品の購入をリクエストします。

    商品の購入をリクエストされたプレイヤーには商品購入ダイアログが表示されます。 商品購入リクエストの結果は、 ClusterScript.onRequestPurchaseStatus のcallbackで受け取ります。

    プレイヤーが商品を購入した場合、 ClusterScript.onPurchaseUpdated のcallbackが呼び出されます。

    プレイヤーが商品を購入せずにダイアログを閉じた場合、購入はキャンセルされます。

    プレイヤーが商品購入ダイアログを表示できない場合、送られたリクエストは無視されます。 例えば、既に商品購入ダイアログが表示されている状態はこれに該当します。

    ルーム種別による挙動の違い:

    イベント会場で実行された場合、商品購入を行うことはできません。ClusterScript.onRequestPurchaseStatus を登録している場合、callbackのstatusとして PurchaseRequestStatus.NotAvailable が渡されます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Example

    const productId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

    $.onStart(() => {
    // プレイヤーの商品所持状況をstateに保存する
    $.state.amounts = {};
    // 購入通知を購読する
    $.subscribePurchase(productId);
    });

    $.onUpdate(deltaTime => {
    // 10秒に1回、定期的に全プレイヤーの購入状況を確認する
    let timer = $.state.timer ?? 0;
    timer -= deltaTime;
    if (timer <= 0) {
    timer += 10;
    const allPlayers = $.getPlayersNear(new Vector3(), Infinity);
    $.getOwnProducts(productId, allPlayers, "onUpdate");
    }
    $.state.timer = timer;
    });

    $.onPurchaseUpdated((player, productId) => {
    // 商品が購入された場合、直ちにそのプレイヤーの購入状況を確認する
    $.getOwnProducts(productId, player, "onPurchaseUpdated");
    });

    $.onGetOwnProducts((ownProducts, meta, errorReason) => {
    // 商品の所持状況をstateに書き込む
    let amounts = $.state.amounts;
    for (let ownProduct of ownProducts) {
    let playerId = ownProduct.player.id;
    let oldAmount = amounts[playerId] ?? 0;
    let newAmount = ownProduct.plusAmount - ownProduct.minusAmount;
    amounts[playerId] = newAmount;
    }
    $.state.amounts = amounts;
    });

    Parameters

    • productId: string

      購入をリクエストする商品のIDです。

    • meta: string

      100 byte以下の文字列です。複数のrequestPurchase呼び出しを識別するために利用できます。空文字や、同じ文字列を複数回指定しても問題ありません。

    Returns void

  • プレイヤーに文字列の入力を要求します。

    入力要求を受けたプレイヤーには文字入力用のUIが表示されます。 プレイヤーが入力した文字列はClusterScript.onTextInputに設定したコールバックで受け取ることができます。 プレイヤーが入力できる文字列は、サイズが1000byte以下かつ文字数が250以下(ただしASCIIは1文字当たり0.5文字で換算します)に制限されます。 プレイヤーが入力要求に応答できない場合、送られた要求は自動的に拒否されます。 例えば、入力要求を受け取って文字列を入力している最中に新たに入力要求を受け取った場合はこれに該当します。 また、プレイヤーは入力要求を意図的に拒否することが可能です。 これらの入力要求の成否はTextInputStatusで表されます。

    Example

    $.onInteract(player => {
    player.requestTextInput("ask_name", "Hi, what is your name?");
    });

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    • meta: string

      100 byte以下の文字列です。複数のrequestTextInput呼び出しを識別するために利用できます。空文字や、同じ文字列を複数回指定しても問題ありません。

    • title: string

      入力要求を受けたプレイヤーの画面に表示される文字列です。200 byte以下である必要があります。

    Returns void

  • プレイヤーに設定された移動速度、ジャンプ速度、重力をリセットします。 PlayerScriptで指定された移動速度、ジャンプ速度、重力もリセットされます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Returns void

  • プレイヤーをリスポーンさせます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Returns void

  • PlayerScriptにメッセージを送ります。 送られた対象はPlayerScript.onReceiveに設定したコールバックを呼ぶことが期待されます。 メッセージのペイロード(arg引数)に使用できるデータについてはSendableを参照してください。

    Example

    以下は適当なメッセージを送る例です。

    playerHandle.send("damage", 20);
    

    以下の例では、アイテムにInteractしたプレイヤーに対して、アイテムのハンドルを送ります。

    $.onInteract(player => {
    player.send("item-handle", $.itemHandle);
    });

    受け取ったメッセージをどう処理するかは、受け取る側のPlayerScriptのPlayerScript.onReceiveに記述します。 以下の例では、受け取ったItemIdを変数に格納します。 このItemIdに対して、必要なときにメッセージのPlayerScript.sendToなどの処理が行えます。

    let itemId = null
    _.onReceive((messageType, arg, sender) => {
    switch (messageType) {
    case "item-handle":
    itemId = arg;
    break;
    }
    });

    PlayerScriptに対して送信されたSendablePlayerScriptSendableに変換されます。 具体的にはItemHandleItemIdに、PlayerHandlePlayerIdに変換されます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒までsendすることができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生しsendは失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    容量の制限:

    エンコードされたargのデータサイズは1000byte以下である必要があります。 データサイズが制限を超えている場合、警告が表示されます。 データサイズはcomputeSendableSizeで計算できます。

    データサイズが制限を大きく超えている場合、ClusterScriptError (requestSizeLimitExceeded) が発生しsendは失敗します。

    Parameters

    • messageType: string

      メッセージの種別を表す100byte以下の任意の文字列

    • arg: Sendable

      メッセージのペイロード

    Returns void

  • プレイヤーにかかる重力加速度(単位:m/s^2)を変更します。初期値は-9.81です。

    PlayerScript.setGravityと設定を共有します。 あとから呼び出した方の値で上書きされます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    • gravity: number

      重力加速度

    Returns void

  • プレイヤーのアバターモデルの姿勢を、指定したHumanoidPoseで上書きします。 姿勢の上書き方法についてはoptionで指定することができます。optionで指定できるプロパティについては SetHumanoidPoseOption を参照してください。

    引数のoptionは省略することができます。省略した場合にはデフォルトの設定値が用いられます。

    HumanoidPoseのrootPosition, rootRotation, muscleのうち、指定されていない要素については上書きされません。 また、指定されていない要素についてはoption.timeoutSeconds、および option.timeoutTransitionSeconds は挙動に影響を与えず、上書きされない状態が継続します。 姿勢の上書きは、次にsetHumanoidPoseが呼び出される、もしくはoptionで指定したtimeoutで姿勢が解除されるまで継続します。

    引数にnullまたは空のHumanoidPoseを渡すことで、setHumanoidPoseによるポーズの上書きを全て解除することができます。 引数にnullまたは空のHumanoidPoseをoptionと一緒に渡した場合、option.transitionSeconds かけて解除された状態に遷移します。

    setHumanoidPoseによるポーズの上書きは、エモートやRidableItemによる姿勢の変更よりも優先されます。

    VRではプレイヤーが掴んでいるアイテムは指定されたポーズに追従しますが、1人称のカメラやUI操作などは影響を受けません。

    Example

    // MyAnimationというIdのHumanoidAnimationを取得する。
    const animation = $.humanoidAnimation("MyAnimation");
    // ポーズを上書きする。
    playerHandle.setHumanoidPose(animation.getSample(0));
    // 上書きを解除する。
    playerHandle.setHumanoidPose(null);
    const animation = $.humanoidAnimation("MyAnimation");
    const interval = 0.1;
    const animationLength = animation.getLength();

    // Interactした人をアニメーションの対象にする
    $.onInteract(player => {
    if ($.state.player) {
    // すでに対象がいるときは解除
    $.state.player.setHumanoidPose(null);
    }
    $.state.animationTime = 0;
    $.state.waitingTime = 0;
    $.state.player = player;
    });

    $.onUpdate(deltaTime => {
    let player = $.state.player;
    if (!player || !player.exists()) return;

    let animationTime = $.state.animationTime + deltaTime;
    if (animationTime > animationLength) {
    animationTime = animationTime % animationLength;
    }
    let waitingTime = $.state.waitingTime + deltaTime;
    if (waitingTime >= interval) {
    let pose = animation.getSample(animationTime);
    // 前回送信時からの時間分だけかけて姿勢を遷移させる
    player.setHumanoidPose(pose, {transitionSeconds: waitingTime});
    waitingTime = 0;
    }
    $.state.animationTime = animationTime;
    $.state.waitingTime = waitingTime;
    });

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    Returns void

  • プレイヤーのジャンプ速度の倍率を変更します。初期値は1です。

    PlayerScript.setJumpSpeedRateと設定を共有します。 あとから呼び出した方の値で上書きされます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    • jumpSpeedRate: number

      ジャンプ速度の倍率

    Returns void

  • プレイヤーの移動速度の倍率を変更します。初期値は1です。

    PlayerScript.setMoveSpeedRateと設定を共有します。 あとから呼び出した方の値で上書きされます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    • moveSpeedRate: number

      移動速度の倍率

    Returns void

  • プレイヤーの位置を変更します。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    • position: Vector3

      足元の中心位置の移動先 (グローバル座標)

    Returns void

  • Beta

    プレイヤーにポストプロセスエフェクトを設定します。

    このメソッドを呼び出すたびに、以前設定されていたPostProcessEffectsは新しいPostProcessEffectsで上書きされます。

    nullを設定するとすべてのエフェクトがクリアされます。

    PlayerScript.setPostProcessEffectsと設定を共有します。 あとから呼び出した方の値で上書きされます。

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Example

    // Interactするととても眩しくなるアイテム
    $.onInteract((player) => {
    const effects = new PostProcessEffects();
    effects.bloom.active = true;
    effects.bloom.threshold.setValue(0.5);
    effects.bloom.intensity.setValue(10.0);
    player.setPostProcessEffects(effects);
    });

    Parameters

    Returns void

  • プレイヤーの向きを変更します。 体の向きは鉛直のままで、y軸回転以外は動きません

    頻度の制限:

    ひとつのアイテムは、最大で10回/秒まで他のハンドルに対して操作することができます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

    流量制御:

    このAPIを含む、他のアイテム・プレイヤーの状態を変更するAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

    Parameters

    • rotation: Quaternion

      プレイヤーの向き (グローバル座標)

    Returns void

Generated using TypeDoc