Class PlayerHandleItem

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

頻度の制限:

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

流量制御:

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

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

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

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

Returns

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

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

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

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

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

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

商品の購入をリクエストされたプレイヤーには商品購入ダイアログが表示されます。 商品購入リクエストの結果は、 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;
});

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

入力要求を受けたプレイヤーには文字入力用の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がスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

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

頻度の制限:

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

流量制御:

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

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

頻度の制限:

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

流量制御:

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

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に対して送信されたSendableはPlayerScriptSendableに変換されます。 具体的にはItemHandleがItemIdに、PlayerHandleがPlayerIdに変換されます。

頻度の制限:

sendを呼び出すことができる頻度には制限があります。

• このスクリプトを実行しているアイテムがクラフトアイテムであった場合、ひとつのアイテムあたり10回/秒以下
• このスクリプトを実行しているアイテムがワールドアイテムであった場合、スペース内の全てのワールドアイテムからの send, send, sendTo の呼び出し回数の合計が3000回/秒以下

瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

流量制御:

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

流量制御による制限:

このスクリプトを実行しているアイテムがワールドアイテムである場合、sendが動作するためには、流量制御による遅延が30秒以下である必要があります。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

容量の制限:

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

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

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

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

頻度の制限:

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

流量制御:

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

プレイヤーのアバターモデルの姿勢を、指定した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がスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。 詳しくは流量制御を参照してください。

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

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

頻度の制限:

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

流量制御:

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

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

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

頻度の制限:

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

流量制御:

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

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

頻度の制限:

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

流量制御:

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

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

このメソッドを呼び出すたびに、以前設定されていた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);
});

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

頻度の制限:

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

流量制御:

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