Interface PlayerScript`Player`

PlayerScriptを操作するハンドルです。_オブジェクトからアクセスできます。

PlayerScriptはClusterScript.setPlayerScriptで設定することで生成されます。

interface PlayerScript {
    cameraHandle: CameraHandle;
    hapticsHandle: HapticsHandle;
    isAndroid: boolean;
    isDesktop: boolean;
    isIos: boolean;
    isMacOs: boolean;
    isMobile: boolean;
    isVr: boolean;
    isWindows: boolean;
    oscHandle: OscHandle;
    playerId: PlayerId;
    sourceItemId: ItemId;
    addVelocity(velocity: Vector3): void;
    computeSendableSize(arg: PlayerScriptSendable): number;
    getAccessoryProductIds(): string[];
    getAvatarMovementFlags(): number;
    getAvatarProductId(): string | null;
    getHumanoidBonePosition(bone: HumanoidBone): Vector3 | null;
    getHumanoidBoneRotation(bone: HumanoidBone): Quaternion | null;
    getIdfc(playerId: PlayerId): string | null;
    getPlayerStorageData(): PlayerScriptSendable;
    getPointerPosition(): Vector2;
    getPosition(): Vector3 | null;
    getPositionOf(playerId: PlayerId): Vector3 | null;
    getRotation(): Quaternion | null;
    getRotationOf(playerId: PlayerId): Quaternion | null;
    getScreenSize(): Vector2;
    getScroll(): Vector2;
    getUserDisplayName(playerId: PlayerId): string | null;
    getUserId(playerId: PlayerId): string | null;
    hideButton(index: number): void;
    humanoidAnimation(humanoidAnimationId: string): HumanoidAnimation;
    iconAsset(iconId: string): IconAsset;
    isMouseLocked(): boolean;
    isPointerPress(pressType: PressType): boolean;
    log(v: any): void;
    onButton(index: number, callback: (isDown: boolean) => void): void;
    onFrame(callback: (deltaTime: number) => void): void;
    onPan(callback: (delta: Vector2) => void): void;
    onReceive(
        callback: (
            messageType: string,
            arg: PlayerScriptSendable,
            sender: PlayerId | ItemId,
        ) => void,
        option?: { item: boolean; player: boolean },
    ): void;
    playerLocalObject(id: string): PlayerLocalObject | null;
    raycast(
        position: Vector3,
        direction: Vector3,
        maxDistance: number,
    ): PlayerScriptRaycastResult | null;
    raycastAll(
        position: Vector3,
        direction: Vector3,
        maxDistance: number,
    ): PlayerScriptRaycastResult[];
    resetPlayerEffects(): void;
    respawn(): void;
    sendAnalytics(analyticsId: string, extensionsJson: string): void;
    sendTo(
        id: PlayerId | ItemId,
        messageType: string,
        arg: PlayerScriptSendable,
    ): void;
    setGravity(gravity: number): void;
    setHumanoidBoneRotationOnFrame(
        bone: HumanoidBone,
        rotation: Quaternion,
    ): void;
    setHumanoidPoseOnFrame(pose: HumanoidPose, weight: number): void;
    setJumpSpeedRate(jumpSpeedRate: number): void;
    setMoveSpeedRate(moveSpeedRate: number): void;
    setPlayerStorageData(data: PlayerScriptSendable): void;
    setPosition(position: Vector3): void;
    setPostProcessEffects(effects: PostProcessEffects | null): void;
    setRotation(rotation: Quaternion): void;
    setVoiceVolumeRateOf(playerId: PlayerId, rate: number): void;
    showButton(index: number, icon: IconAsset): void;
    worldItemReference(worldItemReferenceId: string): ItemId;
}

Index

Properties

`Readonly`cameraHandle

cameraHandle: CameraHandle

カメラワークを制御するためのハンドルを取得します。

`Readonly`hapticsHandle

hapticsHandle: HapticsHandle

プレイヤーのコントローラーやデバイスの振動機能を制御するハンドルを取得します。

`Readonly`isAndroid

isAndroid: boolean

プレイヤーがAndroid環境で入室しているかどうかを取得します。

Quest環境での入室の場合はtrueを返します。

`Readonly`isDesktop

isDesktop: boolean

プレイヤーがデスクトップ環境で入室しているかどうかを取得します。

VR環境やモバイル環境での入室の場合はfalseを返します。

`Readonly`isIos

isIos: boolean

プレイヤーがiOS環境で入室しているかどうかを取得します。

`Readonly`isMacOs

isMacOs: boolean

プレイヤーがmacOS環境で入室しているかどうかを取得します。

`Readonly`isMobile

isMobile: boolean

プレイヤーがモバイル環境で入室しているかどうかを取得します。

VR環境やデスクトップ環境での入室の場合はfalseを返します。

`Readonly`isVr

isVr: boolean

プレイヤーがVRデバイスを使用して入室しているかどうかを取得します。

`Readonly`isWindows

isWindows: boolean

プレイヤーがWindows環境で入室しているかどうかを取得します。

`Readonly`oscHandle

oscHandle: OscHandle

Open Sound Control (OSC)の受信と送信を行うためのハンドルです。

`Readonly`playerId

playerId: PlayerId

プレイヤーのPlayerIdです。

`Readonly`sourceItemId

sourceItemId: ItemId

ClusterScript.setPlayerScriptを呼び出したPlayer Scriptコンポーネントを持っている元のItemのItemIdです。

Methods

addVelocity

addVelocity(velocity: Vector3): void
プレイヤーに速度を加えます。プレイヤーの最終的な移動速度は、加えられた速度とプレイヤー入力の両方から決定されます。プレイヤーが地面に接している間、加えられた速度は摩擦と似たような原理で減速し続けます。
Parameters
- velocity: Vector3
  加えられる速度 (グローバル座標)
Returns void

computeSendableSize

computeSendableSize(arg: PlayerScriptSendable): number
PlayerScriptからデータを送信するときのデータサイズを計算して、byte数を返します。

データがPlayerScriptSendableではない場合はTypeErrorが発生します。
Parameters
- arg: PlayerScriptSendable
Returns number

getAccessoryProductIds

getAccessoryProductIds(): string[]
プレイヤーが現在使用しているアクセサリー商品の商品IDの配列を取得します。

使用しているアクセサリーが商品でない場合は配列に含まれません。
プレイヤーがアクセサリーを編集している間は、アクセサリー編集前に使用していたアクセサリーの商品IDを返します。
プレイヤーがアクセサリーを保存した直後は、直前に使用していたアクセサリーの商品IDを返すことがあります。
プレイヤーが入場した直後は空の配列を返すことがあります。

Returns string[]
プレイヤーが現在使用しているアクセサリーの商品IDの配列。

getAvatarMovementFlags

getAvatarMovementFlags(): number
アバターの移動やモーションに関する状態を、ビットマスクされたフラグの一覧として取得します。定義されているビットフラグは以下の通りです。
- 0x0001: アバターが接地している場合はオン、ジャンプや落下によって空中にいる場合はオフ
- 0x0002: アバターがよじのぼり動作を行っていればオン、そうでなければオフ
- 0x0004: アバターが乗り物に乗っていればオン、そうでなければオフ
フラグは今後のアップデートでも追加される可能性があるため、ビットフラグをマスクした値を使用してください。
Returns number
アバターの移動状態に関するステータス
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}`);
}
```

getAvatarProductId

getAvatarProductId(): string | null
プレイヤーが現在使用しているアバター商品の商品IDを取得します。

使用しているアバターが商品でない場合は null を返します。
プレイヤーがアバターメイカーを起動している間は、アバターメイカー起動前に使用していたアバターの商品IDを返します。
プレイヤーがアバターを変更した直後は、直前に使用していたアバターの商品IDを返すことがあります。
プレイヤーが入場した直後は null を返すことがあります。

Returns string | null
プレイヤーが現在使用しているアバターの商品ID。

getHumanoidBonePosition

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

getHumanoidBoneRotation

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

getIdfc

getIdfc(playerId: PlayerId): string | null
IDFCを取得します。 IDFCはクリエイターがユーザーを一意に認識するために利用できる文字列です。この文字列は32文字で、使われる文字は 0123456789abcdef です。この文字列はPlayerScriptの元となるアイテムをアップロードしたアカウントとユーザーのアカウントとの組によって決定されます。元となるアイテムとは、 $.setPlayerScript() を呼び出したアイテムのことで、 _.sourceItemId で取得できるアイテムとなります。ユーザーの使用するデバイスやスペースによっては変化しません。退室したプレイヤーに対してや、無効なPlayerIdに対してはnullを返します。

この文字列はコンテンツ体験を向上する目的で利用できます。当社が不適切と判断した場合、予告なく利用を制限させていただく場合もあります。
Parameters
- playerId: PlayerId
  取得するプレイヤーのPlayerId
Returns string | null

getPlayerStorageData

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

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

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

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

getPointerPosition

getPointerPosition(): Vector2
現在のポインタの位置を返します。スクリーンの左下を(0, 0)、右上を(1, 1)とする座標系で表されます。

タッチスクリーンの場合、タッチされていない状態で行われたタッチの最後の位置を返します。

アプリケーションが非アクティブな状態では値は更新されません。

マウスロックされている場合やQuest環境では不定な値を返します。

Returns Vector2
現在のポインタの位置

getPosition

getPosition(): Vector3 | null
プレイヤー自身の現在の位置をグローバル座標で取得します。
このメソッドは空間に同期する前のプレイヤーの位置を取得します。

値の取得に失敗した場合、nullを返します。

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

Returns Vector3 | null
プレイヤーの現在の位置

getPositionOf

getPositionOf(playerId: PlayerId): Vector3 | null
空間上に同期された、指定したプレイヤーの現在の位置をグローバル座標で取得します。

値の取得に失敗した場合、nullを返します。
Parameters
- playerId: PlayerId
  取得するプレイヤーのPlayerId
Returns Vector3 | null
プレイヤーの現在の位置

getRotation

getRotation(): Quaternion | null
プレイヤー自身の現在の方向をグローバル座標で取得します。
このメソッドは空間に同期する前のプレイヤーの方向を取得します。

値の取得に失敗した場合、nullを返します。

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

Returns Quaternion | null
プレイヤーの現在の方向

getRotationOf

getRotationOf(playerId: PlayerId): Quaternion | null
空間上に同期された、指定したプレイヤーの現在の方向をグローバル座標で取得します。

値の取得に失敗した場合、nullを返します。
Parameters
- playerId: PlayerId
  取得するプレイヤーのPlayerId
Returns Quaternion | null
プレイヤーの現在の方向

getScreenSize

getScreenSize(): Vector2
clusterアプリケーションの現在のスクリーンサイズを返します。

Quest環境では不定な値を返します。

Returns Vector2
ウィンドウサイズをピクセルで表したもの (xは横方向、yは縦方向)

getScroll

getScroll(): Vector2
マウスホイールなどのこのフレームでのスクロール量を返します。

アプリケーションがアクティブで、アプリケーション上で行われたスクロールのみを取得します。

スクロールに対応している入力デバイスが存在しない場合は0ベクトルを返します。

Returns Vector2
このフレームでのスクロール量をピクセルで表したもの (xは横方向で右方向を正、yは縦方向で上方向を正)。この値はデバイスによって大きく異なる場合があります。

getUserDisplayName

getUserDisplayName(playerId: PlayerId): string | null
プレイヤーの表示名を取得します。ユーザーは自分の表示名を変更することができ、異なるユーザーが同じ表示名を使うことができます。退室したプレイヤーに対してや、無効なPlayerIdに対してはnullを返します。
Parameters
- playerId: PlayerId
  取得するプレイヤーのPlayerId
Returns string | null

getUserId

getUserId(playerId: PlayerId): string | null
プレイヤーのユーザーIDです。ユーザーは自分のユーザーIDを変更することができますが、異なるユーザーが同じユーザーIDを同時にもつことはありません。退室したプレイヤーに対してや、無効なPlayerIdに対してはnullを返します。
Parameters
- playerId: PlayerId
  取得するプレイヤーのPlayerId
Returns string | null

hideButton

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

デスクトップ環境とモバイル環境では、index = 0に対して呼び出した場合は「使う」ボタンの挙動が元に戻り、 UseItemTrigger や ClusterScript.onUse が設定されたアイテムを掴んでいるかどうかに基づいて、「使う」ボタンの表示/非表示が切り替わります。
Parameters
- index: number
  ボタンの番号で、0,1,2,3のいずれか。この範囲外の値を指定するとエラーになります
Returns void

humanoidAnimation

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

HumanoidAnimationListの詳細はドキュメントを参照してください。
Parameters
- humanoidAnimationId: string
Returns HumanoidAnimation

iconAsset

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

isMouseLocked

isMouseLocked(): boolean
マウスロック状態であるかを返します。

モバイル環境やQuest環境ではfalseを返します。

Returns boolean
そのマウスロック状態であるか

isPointerPress

isPointerPress(pressType: PressType): boolean
マウスボタンやタッチが押下されているかを返します。

対応するポインティングデバイスが存在しない場合はfalseを返します。

アプリケーションが非アクティブな状態では値は更新されません。
Parameters
- pressType: PressType
  押下されているかを取得するマウスボタンの種類やタッチ
  
  "leftClick", "rightClick", "middleClick", "touch" が利用できます。
Returns boolean
そのマウスボタンやタッチが押下されているか

log

log(v: any): void
vの内容をtoStringしたものをログに出力します。
Parameters
- v: any
Returns void

onButton

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

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

このコールバックはisDown = trueで呼ばれたあと、必ずしもisDown = falseで呼ばれるとは限りません。例えば、ボタンを押し下げたあとでhideButtonを呼び出してボタンを非表示にした場合、isDown = falseでのコールバックは呼ばれません。
Parameters
- index: number
  ボタンの番号で、0,1,2,3のいずれか。この範囲外の値を指定するとエラーになります
- callback: (isDown: boolean) => void
  ボタンの操作時に呼ばれるcallback関数
Returns void

onFrame

onFrame(callback: (deltaTime: number) => void): void
毎フレーム呼ばれるcallbackを登録します。このコールバックは毎フレーム呼ばれることが保証されています。

複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (deltaTime: number) => void
Returns void
Example
```
// 10秒間隔でログを出力する。
let t = 0;
_.onFrame(deltaTime => {
    t += deltaTime;
    if (t > 10) {
        _.log("10 sec elapsed.");
        t -= 10;
    }
});
```

onPan

onPan(callback: (delta: Vector2) => void): void
非VR環境で視点操作入力が行われたときに呼ばれるコールバック関数を登録します。登録したコールバックは実際に視点の方向が変更されたかに関わらず呼ばれます。

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

特殊なモード（アクセサリー編集中など）の場合、このコールバックは呼ばれません。 VR環境ではこのコールバックは呼ばれません。
Parameters
- callback: (delta: Vector2) => void
  delta = 視点の方向が変更される場合、概ね何度変更されるか (xは横方向で右を向く方向を正、yは縦方向で上を向く方向を正) この値にはユーザーの設定の操作感度や反転が反映されます。
Returns void

onReceive

onReceive(
    callback: (
        messageType: string,
        arg: PlayerScriptSendable,
        sender: PlayerId | ItemId,
    ) => void,
    option?: { item: boolean; player: boolean },
): void
PlayerHandle.send、またはPlayerScript.sendToでPlayerId宛てに送られたメッセージを受け取ったときに呼ばれるcallbackを登録します。

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

option

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 から送信されたメッセージを受け取ります。
Parameters
- callback: (
      messageType: string,
      arg: PlayerScriptSendable,
      sender: PlayerId | ItemId,
  ) => void
  senderは送信元のアイテムまたはプレイヤーを表します。
- Optionaloption: { item: boolean; player: boolean }
  コールバックの登録のオプションです。受け取るメッセージの種類を指定できます。
Returns void
Example
```
// 送られたメッセージをログを出力する。
_.onReceive((messageType, arg, sender) => {
  _.log(`Received message: ${messageType}, ${arg}`);
});
```
Example
```
// 送られたメッセージをログを出力する。アイテムからのメッセージのみを受け取る。
_.onReceive((messageType, arg, sender) => {
  _.log(`Received message: ${messageType}, ${arg}`);
}, { player: false, item: true });
```

playerLocalObject

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

raycast

raycast(
    position: Vector3,
    direction: Vector3,
    maxDistance: number,
): PlayerScriptRaycastResult | null
レイが最初に衝突した物体を取得します。
Parameters
- position: Vector3
  レイの原点 (グローバル座標)
- direction: Vector3
  レイの方向 (グローバル座標)
- maxDistance: number
  衝突判定を行う最大距離
Returns PlayerScriptRaycastResult | null
衝突した物体 (衝突しなかった場合はnull)

raycastAll

raycastAll(
    position: Vector3,
    direction: Vector3,
    maxDistance: number,
): PlayerScriptRaycastResult[]
レイが衝突した全ての物体を取得します。

大量のコライダーが範囲に含まれる場合に、条件を満たしたすべてのItemHandleを取得できない場合があります。この場合、コンソールに警告メッセージが出力されます。
Parameters
- position: Vector3
  レイの原点 (グローバル座標)
- direction: Vector3
  レイの方向 (グローバル座標)
- maxDistance: number
  衝突判定を行う最大距離
Returns PlayerScriptRaycastResult[]
衝突した物体の配列 (順序は未定義)

resetPlayerEffects

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

Returns void

respawn

respawn(): void
プレイヤーをリスポーンさせます。

Returns void

sendAnalytics

sendAnalytics(analyticsId: string, extensionsJson: string): void
分析用のデータをclusterのサーバーに送信します。このAPIは有償機能の利用者向けの機能です。

データサイズ・頻度・通信状況などによってはデータが送信されない場合があります。
Parameters
- analyticsId: string
  分析用 ID
- extensionsJson: string
  分析用のデータ。Json形式であることが期待されます。
Returns void

sendTo

sendTo(
    id: PlayerId | ItemId,
    messageType: string,
    arg: PlayerScriptSendable,
): void
アイテムまたはプレイヤーにメッセージを送ります。
アイテムは送信されたメッセージをオプションに{ player: true }を指定したClusterScript.onReceiveに設定したコールバックで受け取ることができます。
プレイヤーは送信されたメッセージをPlayerScript.onReceiveに設定したコールバックで受け取ることができます。
メッセージのペイロード（arg引数）に使用できるデータについてはPlayerScriptSendableを参照してください。

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

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

undefined など、PlayerScriptSendableではない値をペイロードとしてarg引数に渡した場合、無視されます。この挙動は将来的に変更される可能性があります。

頻度の制限

sendToを呼び出すことができる頻度には制限があります。
- クラフトアイテムからの呼び出しであった場合、ひとつのアイテムあたり10回/秒以下
- ワールドアイテムからの呼び出しであった場合、スペース内の全てのワールドアイテムからの ItemHandle.send, PlayerHandle.send, PlayerScript.sendTo の呼び出し回数の合計が3000回/秒以下
瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

流量制御

このAPIを含む、流量制御の対象となるAPIがスペース内で限度を超えて頻繁に呼び出され続けた場合、結果の反映が大きく遅延することがあります。詳しくは流量制御を参照してください。

流量制御による制限

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

容量の制限

エンコードされたargのデータサイズは以下の制限を満たす必要があります。
- ワールドアイテムによって登録されたPlayerScriptからメッセージを送信する場合、100kB以下である
- クラフトアイテムによって登録されたPlayerScriptからメッセージを送信する場合、1000byte以下である
データサイズが制限を超えている場合、警告が表示されるか、 ClusterScriptError (requestSizeLimitExceeded) が発生しsendが失敗します。データサイズはPlayerScript.computeSendableSizeで計算できます。
Parameters
- id: PlayerId | ItemId
  送信先のアイテムまたはプレイヤー
- messageType: string
  メッセージの種別を表す100byte以下の任意の文字列
- arg: PlayerScriptSendable
  メッセージのペイロード
Returns void

setGravity

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

PlayerHandle.setGravityと設定を共有します。あとから呼び出した方の値で上書きされます。
Parameters
- gravity: number
  重力加速度
Returns void

setHumanoidBoneRotationOnFrame

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

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

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

setHumanoidPoseOnFrame

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

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

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

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

setJumpSpeedRate

setJumpSpeedRate(jumpSpeedRate: number): void
プレイヤーのジャンプ速度の倍率を変更します。初期値は1です。

PlayerHandle.setJumpSpeedRateと設定を共有します。あとから呼び出した方の値で上書きされます。
Parameters
- jumpSpeedRate: number
  ジャンプ速度の倍率
Returns void

setMoveSpeedRate

setMoveSpeedRate(moveSpeedRate: number): void
プレイヤーの移動速度の倍率を変更します。初期値は1です。

PlayerHandle.setMoveSpeedRateと設定を共有します。あとから呼び出した方の値で上書きされます。
Parameters
- moveSpeedRate: number
  移動速度の倍率
Returns void

setPlayerStorageData

setPlayerStorageData(data: PlayerScriptSendable): void
プレイヤーのPlayerStorageにデータを上書き保存します。

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

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

PlayerStorageとは

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

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

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

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

容量の制限

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

データサイズが制限を超えている場合、ClusterScriptError (requestSizeLimitExceeded) が発生しsetPlayerStorageDataは失敗します。
Parameters
- data: PlayerScriptSendable
Returns void
Example
```
// レベルアップのメッセージを受け取るとレベルアップし、その結果を保存するコードの例
let level = 1;
_.onReceive((messageType, arg, sender) => {
  if (messageType === "levelUp") {
    level += 1;
    _.setPlayerStorageData({ level });
  }
});
```

setPosition

setPosition(position: Vector3): void
プレイヤー自身の位置をグローバル座標で設定します。
このメソッドは空間に同期する前のプレイヤーの位置を設定します。
Parameters
- position: Vector3
  プレイヤーの位置
Returns void

setPostProcessEffects

setPostProcessEffects(effects: PostProcessEffects | null): void
Beta
プレイヤーにポストプロセスエフェクトを設定します。

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

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

PlayerHandle.setPostProcessEffectsと設定を共有します。あとから呼び出した方の値で上書きされます。
Parameters
- effects: PostProcessEffects | null
  PostProcessEffectsのインスタンス。
Returns void
Example
```
// 押すととてもまぶしくなるボタン
_.onButton(0, (isDown) => {
    if (!isDown) return;
    const effects = new PostProcessEffects();
    effects.bloom.active = true;
    effects.bloom.threshold.setValue(0.5);
    effects.bloom.intensity.setValue(10.0);
    _.setPostProcessEffects(effects);
});
```

setRotation

setRotation(rotation: Quaternion): void
プレイヤー自身の方向をグローバル座標で設定します。
このメソッドは空間に同期する前のプレイヤーの方向を設定します。

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

setVoiceVolumeRateOf

setVoiceVolumeRateOf(playerId: PlayerId, rate: number): void
指定したプレイヤーのボイスが、このPlayerScriptを実行するプレイヤーに対して聞こえる音量を変更します。自分自身への設定は無視されます。

この設定はPlayer Scriptの有効期間が終了した場合にリセットされます。
Parameters
- playerId: PlayerId
  設定するプレイヤーのPlayerId。
- rate: number
  設定する音量の割合。指定した値は0以上1以下の範囲内に収められます。
Returns void

showButton

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

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

デスクトップ環境とモバイル環境では、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キー
VR環境では、ボタンを1つ以上有効にしている間に右手コントローラーのトリガーを引くことでパイメニューが表示され、スティックを倒すことでボタン入力が行えます。パイメニューのボタンは、右から反時計回りに0,1,2,3に対応します。

デスクトップ環境では、ボタンを1つ以上表示している間は画面上でマウスカーソル操作がロックされ、マウスロック中のクリックやキー入力がボタン入力として扱われます。ボタンの表示や非表示を著しく高頻度で繰り返した場合、この自動でのマウスロックは一定時間無効になります。
Parameters
- index: number
  ボタンの番号で、0,1,2,3のいずれか。この範囲外の値を指定するとエラーになります
- icon: IconAsset
  表示するアイコン画像。無効なアイコンを指定した場合、アイコンが未指定なものとして扱われます。
Returns void

worldItemReference

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

WorldItemReferenceListの詳細はドキュメントを参照してください。
Parameters
- worldItemReferenceId: string
Returns ItemId
Example
```
// ボタン0を使用すると指定したアイテムに "button" というメッセージを送信するアイテム
const target = _.worldItemReference("target");

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

Interface PlayerScriptPlayer

Index

Properties

Methods

Properties

ReadonlycameraHandle

ReadonlyhapticsHandle

ReadonlyisAndroid

ReadonlyisDesktop

ReadonlyisIos

ReadonlyisMacOs

ReadonlyisMobile

ReadonlyisVr

ReadonlyisWindows

ReadonlyoscHandle

ReadonlyplayerId

ReadonlysourceItemId

Methods

addVelocity

Parameters

Returns void

computeSendableSize

Parameters

Returns number

getAccessoryProductIds

Returns string[]

getAvatarMovementFlags

Returns number

Example

getAvatarProductId

Returns string | null

getHumanoidBonePosition

Parameters

Returns Vector3 | null

getHumanoidBoneRotation

Parameters

Returns Quaternion | null

getIdfc

Parameters

Returns string | null

getPlayerStorageData

Returns PlayerScriptSendable

Example

getPointerPosition

Returns Vector2

getPosition

Returns Vector3 | null

getPositionOf

Parameters

Returns Vector3 | null

getRotation

Returns Quaternion | null

getRotationOf

Parameters

Returns Quaternion | null

getScreenSize

Returns Vector2

getScroll

Returns Vector2

getUserDisplayName

Parameters

Returns string | null

getUserId

Parameters

Returns string | null

hideButton

Parameters

Returns void

humanoidAnimation

Parameters

Returns HumanoidAnimation

iconAsset

Parameters

Returns IconAsset

isMouseLocked

Returns boolean

isPointerPress

Parameters

Returns boolean

log

Interface PlayerScript`Player`

`Readonly`cameraHandle

`Readonly`hapticsHandle

`Readonly`isAndroid

`Readonly`isDesktop

`Readonly`isIos

`Readonly`isMacOs

`Readonly`isMobile

`Readonly`isVr

`Readonly`isWindows

`Readonly`oscHandle

`Readonly`playerId

`Readonly`sourceItemId