Interface PlayerScriptPlayer Beta

PlayerScriptからデータを送信するときのデータサイズを計算して、byte数を返します。 sendに対応していないデータの場合はTypeErrorが発生します。

アバターの移動やモーションに関する状態を、ビットマスクされたフラグの一覧として取得します。 定義されているビットフラグは以下の通りです。

• 0x0001: アバターが接地している場合はオン、ジャンプや落下によって空中にいる場合はオフ
• 0x0002: アバターがよじのぼり動作を行っていればオン、そうでなければオフ
• 0x0004: アバターが乗り物に乗っていればオン、そうでなければオフ

フラグは今後のアップデートでも追加される可能性があるため、ビットフラグをマスクした値を使用してください。

Example

// ビットフラグを取得してログ出力する関数の例
function getStatus() {
  let flags = _.getAvatarMovementFlags();
  let isGrounded = (flags & 0x0001) !== 0;
  let isClimbing = (flags & 0x0002) !== 0;
  let isRiding = (flags & 0x0004) !== 0;
  _.log(`isGrounded: ${isGrounded}, isClimbing: ${isClimbing}, isRiding: ${isRiding}`);
}

Returns

アバターの移動状態に関するステータス

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

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

プレイヤーのPlayerStorageに保存されたデータを取得します。

クラフトアイテムで実行した場合はエラーになります。

PlayerStorageの詳細はsetPlayerStorageDataを参照してください。

Example

// プレイヤーのゲーム開始時に保存されたレベルを取得するコードの例
let level;
const storageData = _.getPlayerStorageData();
if (storageData === null) {
  level = 1;
} else {
  level = storageData.level;
}

Returns

PlayerStorageに現在保存されているデータ

プレイヤーの現在の位置をグローバル座標で取得します。

アバターがロード中である場合、nullを返します。

プレイヤーの移動状況をより詳細に取得するには、この関数に加えて PlayerScript.getAvatarMovementFlags を利用します。

Returns

プレイヤーの現在の位置

プレイヤーの現在の方向をグローバル座標で取得します。

アバターがロード中である場合、nullを返します。

プレイヤーの移動状況をより詳細に取得するには、この関数に加えて PlayerScript.getAvatarMovementFlags を利用します。

Returns

プレイヤーの現在の方向

PlayerScript.showButtonで表示したボタン等を非表示にします。 すでに非表示のボタンに対して呼び出した場合は何も起こりません。

index = 0に対して呼び出した場合は「使う」ボタンの挙動が元に戻り、 UseItemTrigger や ClusterScript.onUse が設定されたアイテムを掴んでいるかどうかに基づいて、「使う」ボタンの表示/非表示が切り替わります。

アイテムのHumanoidAnimationListに含まれる、humanoidAnimationIdに指定したidのアニメーションを参照するHumanoidAnimationオブジェクトを返します。

HumanoidAnimationListの詳細はドキュメントを参照してください。

アイテムのIcon Asset Listコンポーネントで定義された、iconIdに指定したidに該当するアイコン画像オブジェクトを返します。 詳細はIcon Asset Listを参照してください。 このアイコンは PlayerScript.showButton で表示するために使用できます。

vの内容をtoStringしたものをログに出力します。

PlayerScript.showButtonで表示したボタンの操作時に呼ばれるコールバック関数を登録します。 コールバックはボタンを押し下げると isDown = true で呼び出され、その後にボタンを離すと isDown = false で呼び出されます。 この関数はボタンの表示状態と関係なく登録でき、ボタンを非表示にしても登録状態は保持されます。

VR環境では PlayerScript.showButton を呼んでも何も起こらないため、この方法で登録したコールバックは呼び出されません。 プレイヤーがVR環境であるかどうかは PlayerScript.isVr を用いて確認できます。

複数回呼ばれた場合、ボタン番号ごとに最後の登録のみが有効です。

このコールバックはisDown = trueで呼ばれたあと、必ずしもisDown = falseで呼ばれるとは限りません。 例えば、ボタンを押し下げたあとでhideButtonを呼び出してボタンを非表示にした場合、isDown = falseでのコールバックは呼ばれません。

毎フレーム呼ばれるcallbackを登録します。 このコールバックは毎フレーム呼ばれることが保証されています。

複数回呼ばれた場合、最後の登録のみが有効です。

Example

// 10秒間隔でログを出力する。
let t = 0;
_.onFrame(deltaTime => {
    t += deltaTime;
    if (t > 10) {
        _.log("10 sec elapsed.");
        t -= 10;
    }
});

PlayerHandle.send、またはPlayerScript.sendToでPlayerId宛てに送られたメッセージを受け取ったときに呼ばれるcallbackを登録します。

複数回呼ばれた場合、最後の登録のみが有効です。

optionで受け取るメッセージの種類を指定できます。

optionが未設定の場合、 PlayerHandle.sendからのメッセージとPlayerScript.sendToでPlayerId宛てに送られたメッセージの両方を受け取ります。

• option.item が true の場合、PlayerHandle.send から送信されたメッセージを受け取ります。
• option.item が false の場合、PlayerHandle.send から送信されたメッセージを無視します。
• option.item が未設定の場合、PlayerHandle.send から送信されたメッセージを受け取ります。
• option.player が true の場合、PlayerScript.sendTo から送信されたメッセージを受け取ります。
• option.player が false の場合、PlayerScript.sendTo から送信されたメッセージを無視します。
• option.player が未設定の場合、PlayerScript.sendTo から送信されたメッセージを受け取ります。

Example

// 送られたメッセージをログを出力する。
_.onReceive((messageType, arg, sender) => {
  _.log(`Received message: ${messageType}, ${arg}`);
});

Example

// 送られたメッセージをログを出力する。アイテムからのメッセージのみを受け取る。
_.onReceive((messageType, arg, sender) => {
  _.log(`Received message: ${messageType}, ${arg}`);
}, { player: false, item: true });

このPlayerScriptが初期化されたとき、 初めてonFrameが実行される前に一度だけ呼ばれるcallbackを登録します。

このPlayerScriptが初期化されたときとは、 $.setPlayerScript()を利用して アイテムに添付したPlayer Scriptコンポーネントのスクリプトが PlayerScriptに登録され スクリプトがロードされて有効化されたときを指します。

複数回呼ばれた場合、最後の登録のみが有効になります。

Deprecated

_.onStart() は廃止予定です。 PlayerScriptの初期化時に一度だけ実行する処理は、代わりに、スクリプトのトップレベルに直接書いてください。

Example

// NG
_.onStart(() => {
  _.log("PlayerScript is initialized.");
});

// OK
_.log("PlayerScript is initialized.");

アイテムのPlayer Local Object Reference Listコンポーネントで定義された、idに指定したidに該当するオブジェクトを返します。 詳細はPlayer Local Object Reference Listを参照してください。 定義されていないidを指定した場合や、オブジェクトは存在するもののコンポーネントで指定された条件にマッチしない場合にはnullを返します。

レイが最初に衝突した物体を取得します。

Returns

衝突した物体 (衝突しなかった場合はnull)

レイが衝突した全ての物体を取得します。

大量のコライダーが範囲に含まれる場合に、条件を満たしたすべてのItemHandleを取得できない場合があります。 この場合、コンソールに警告メッセージが出力されます。

Returns

衝突した物体の配列 (順序は未定義)

アイテム・プレイヤーにメッセージを送ります。 送られた対象はClusterScript.onReceiveやPlayerScript.onReceiveに設定したコールバックを呼ぶことが期待されます。 メッセージのペイロード（arg引数）に使用できるデータについてはPlayerScriptSendableを参照してください。

削除されたアイテムに対してや、無効なItemIdに対しては無視されます。 退室したプレイヤーに対してや、無効なPlayerIdに対しては無視されます。

ItemIdに対して送信した場合、PlayerScriptSendableはSendableに変換されます。

ひとつの PlayerScript は、最大で10回/秒までメッセージを送信できます。 瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。 制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生しsendToは失敗します。

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

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

プレイヤーのアバターモデルの特定ボーンの回転を、指定した値にします。 回転はグローバル回転で指定します。 この関数で適用したボーンの回転はそのフレームでのみ適用され、次フレーム以降には影響しません。

アバターに存在しないボーンを指定してこの関数を呼び出した場合は、何も起こりません。

この関数で指定したボーンの回転は、PlayerHandle.setHumanoidPose よりも優先されます。 VRではプレイヤーが掴んでいるアイテムは指定されたポーズに追従しますが、1人称のカメラやUI操作などは影響を受けません。

プレイヤーのアバターモデルの姿勢を、指定したHumanoidPoseで上書きします。 この関数で適用した姿勢はそのフレームのみで適用され、次フレーム以降には影響しません。

HumanoidPoseのrootPosition, rootRotation, muscleのうち、指定されていない要素については上書きされません。

weightは指定した姿勢の適用率を0以上1以下で表し、1を指定すると姿勢が完全に適用されます。 weightは省略でき、省略した場合は1が指定されたものとして扱われます。

この関数で指定した姿勢は PlayerHandle.setHumanoidPose よりも優先されます。 VRではプレイヤーが掴んでいるアイテムは指定されたポーズに追従しますが、1人称のカメラやUI操作などは影響を受けません。

プレイヤーのPlayerStorageにデータを上書き保存します。

保存できるデータ（data引数）についてはPlayerScriptSendableを参照してください。

クラフトアイテムで実行した場合はエラーになります。

PlayerStorageは、各ワールドやイベントでプレイヤーごとに存在する、データを保存するための領域です。 一度もsetPlayerStorageDataが呼ばれていないPlayerStorageにはnullが保存されています。

ワールドでは、プレイヤーがワールドを離れてもPlayerStorageのデータは保持されます。 プレイヤーが再びそのワールドに戻ると、以前のデータを参照できます。 PlayerStorageにはPlayerId, ItemIdを保存することもできますが、これらはスペースをまたいで有効なプレイヤーやアイテムを指し示すとは限りません。

イベントでは、プレイヤーがイベントに入場するたびに、PlayerStorageは初期化され、nullがセットされます。 また、イベントでPlayerStorageのデータが上書きされても、イベント開催会場となった元のワールドのPlayerStorageのデータは変更されません。

PlayerStorageのデータはワールド管理画面から消去することができます。 詳しくはこちらを参照してください。

エンコードされたdataのデータサイズは10,000byte以下である必要があります。 データサイズはcomputeSendableSizeで計算できます。

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

Example

// レベルアップのメッセージを受け取るとレベルアップし、その結果を保存するコードの例
let level = 1;
_.onReceive((messageType, arg, sender) => {
  if (messageType === "levelUp") {
    level += 1;
    _.setPlayerStorageData({ level });
  }
});

プレイヤーの位置をグローバル座標で設定します。

プレイヤーの方向をグローバル座標で設定します。

この関数ではy軸回転のみが適用され、プレイヤーの向きは鉛直のままになります。

指定した整数値に対応したボタンUIを表示するか、あるいはボタンと同等に扱われるキー/マウスクリック入力等の監視を開始します。 表示済みのボタンに対して呼び出した場合、必要に応じてアイコンが更新されます。 この方法で最大4つのボタン入力を提示できます。

この関数でボタンを表示するには、ワールドのWorldRuntimeSetting コンポーネントで Use Cluster HUD v2 オプションが有効になっている必要があります。 表示したボタンのコールバックは PlayerScript.onButton で登録します。

この関数はデスクトップやモバイルでのみ動作し、VR環境では呼び出しても何も起こりません。 この方法で提示したボタンは特にモーションの実行など、VR環境ではないユーザーの表現力を向上する用途に適しています。 プレイヤーがVR環境であるかどうかは PlayerScript.isVr を用いて確認できます。

index = 0に対応するボタンは、UseItemTrigger が設定されたのアイテムの「使う」ボタンと共通のボタンです。 それ以外のボタンは、この関数を呼び出すことでのみ表示されます。

index = 0でこの関数を呼び出した場合、 PlayerScript.hideButton をindex = 0で呼び出すまでの間、 アイテムの「使う」ボタンよりも、この関数で設定したボタンの表示内容と PlayerScript.onButton で登録したコールバックが優先されます。 ボタンを押しても UseItemTrigger は発火せず、 ClusterScript.onUse も呼ばれなくなります。

この関数で表示したボタンは PlayerScript.hideButton を呼び出すか、あるいはPlayer Scriptの有効期間が終了することで非表示になります。

モバイル環境では、ボタンは番号に応じて特定の位置に配置されます。 デスクトップ環境では、ボタン0,1,2,3に対してそれぞれ以下のキーアサインが適用されます。

• 0: 左クリック
• 1: 右クリック
• 2: Eキー
• 3: Rキー

デスクトップ環境では、ボタンを1つ以上表示している間は画面上でカーソル操作がロックされ、カーソルロック中のクリックやキー入力がボタン入力として扱われます。 ボタンの表示や非表示を著しく高頻度で繰り返した場合、この自動でのカーソルロックは一定時間無効になります。

アイテムのWorldItemReferenceListに含まれる、worldItemReferenceIdが指定されたアイテムを参照するItemIdオブジェクトを返します。

WorldItemReferenceListの詳細はドキュメントを参照してください。

Example

// ボタン0を使用すると指定したアイテムに "button" というメッセージを送信するアイテム
const target = _.worldItemReference("target");

_.onButton(0, isDown => {
  if (isDown) _.sendTo(target, "button", null);
});