Interface ClusterScript`Item`

アイテム自身を操作するハンドルです。個々のアイテムごとに存在し、$オブジェクトからアクセスできます。

interface ClusterScript {
    angularVelocity: Vector3;
    groupState: StateProxy;
    id: string;
    itemHandle: ItemHandle;
    itemTemplateId: ItemTemplateId | null;
    state: StateProxy;
    useGravity: boolean;
    velocity: Vector3;
    addForce(force: Vector3): void;
    addForceAt(force: Vector3, position: Vector3): void;
    addImpulsiveForce(impulsiveForce: Vector3): void;
    addImpulsiveForceAt(impulsiveForce: Vector3, position: Vector3): void;
    addImpulsiveTorque(impulsiveTorque: Vector3): void;
    addTorque(torque: Vector3): void;
    audio(itemAudioSetId: string): ApiAudio;
    audioLink(): AudioLinkHandle;
    callExternal(
        endpointId: ExternalEndpointId,
        request: string,
        meta: string,
    ): void;
    callExternal(request: string, meta: string): void;
    clearVisiblePlayers(): void;
    computeSendableSize(arg: Sendable): number;
    createItem(
        itemTemplateId: ItemTemplateId | WorldItemTemplateId,
        position: Vector3,
        rotation: Quaternion,
    ): ItemHandle;
    createItem(
        itemTemplateId: ItemTemplateId | WorldItemTemplateId,
        position: Vector3,
        rotation: Quaternion,
        option: CreateItemOption,
    ): ItemHandle;
    destroy(): void;
    getGrabbingPlayer(): PlayerHandle | null;
    getItemsNear(position: Vector3, radius: number): ItemHandle[];
    getLatestComments(count: number): Comment[];
    getOverlaps(): Overlap[];
    getOwner(): PlayerHandle;
    getOwnProducts(
        productId: string,
        players: PlayerHandle | PlayerHandle[],
        meta: string,
    ): void;
    getPlayersNear(position: Vector3, radius: number): PlayerHandle[];
    getPosition(): Vector3;
    getRidingPlayer(): PlayerHandle | null;
    getRotation(): Quaternion;
    getStateCompat(
        target: CompatGimmickTarget,
        key: string,
        parameterType: CompatParamType,
    ): Date | CompatSendable | undefined;
    getUnityComponent(type: string): UnityComponent | null;
    humanoidAnimation(humanoidAnimationId: string): HumanoidAnimation;
    isEvent(): boolean;
    log(v: any): void;
    material(materialId: string): MaterialHandle;
    onCollide(callback: (collision: Collision) => void): void;
    onCommentReceived(callback: (comments: Comment[]) => void): void;
    onExternalCallEnd(
        callback: (
            response: string | null,
            meta: string,
            errorReason: string | null,
        ) => void,
    ): void;
    onGetOwnProducts(
        callback: (
            ownProducts: OwnProduct[] | null,
            meta: string,
            errorReason: string | null,
        ) => void,
    ): void;
    onGiftSent(callback: (gifts: GiftInfo[]) => void): void;
    onGrab(
        callback: (
            isGrab: boolean,
            isLeftHand: boolean,
            player: PlayerHandle,
        ) => void,
    ): void;
    onInteract(callback: (player: PlayerHandle) => void): void;
    onPhysicsUpdate(callback: (deltaTime: number) => void): void;
    onPurchaseUpdated(
        callback: (player: PlayerHandle, productId: string) => void,
    ): void;
    onReceive(
        callback: (
            messageType: string,
            arg: Sendable,
            sender: ItemHandle | PlayerHandle,
        ) => void,
        option?: { item: boolean; player: boolean },
    ): void;
    onRequestGrantProductResult(
        callback: (result: ProductGrantResult) => void,
    ): void;
    onRequestPurchaseStatus(
        callback: (
            meta: string,
            status: PurchaseRequestStatus,
            errorReason: string | null,
            player: PlayerHandle,
        ) => void,
    ): void;
    onRide(callback: (isGetOn: boolean, player: PlayerHandle) => void): void;
    onStart(callback: () => void): void;
    onSteer(callback: (input: Vector2, player: PlayerHandle) => void): void;
    onSteerAdditionalAxis(
        callback: (input: number, player: PlayerHandle) => void,
    ): void;
    onTextInput(
        callback: (text: string, meta: string, status: TextInputStatus) => void,
    ): void;
    onUpdate(callback: (deltaTime: number) => void): void;
    onUse(callback: (isDown: boolean, player: PlayerHandle) => void): void;
    raycast(
        position: Vector3,
        direction: Vector3,
        maxDistance: number,
    ): RaycastResult | null;
    raycastAll(
        position: Vector3,
        direction: Vector3,
        maxDistance: number,
    ): RaycastResult[];
    requestOwner(player: PlayerHandle): void;
    sendSignalCompat(target: CompatStateTarget, key: string): void;
    setPlayerScript(playerHandle: PlayerHandle): void;
    setPosition(v: Vector3): void;
    setRotation(v: Quaternion): void;
    setStateCompat(
        target: CompatStateTarget,
        key: string,
        value: CompatSendable,
    ): void;
    setVisiblePlayers(players: PlayerHandle[]): void;
    subNode(subNodeName: string): SubNode;
    subscribePurchase(productId: string): void;
    unsubscribePurchase(productId: string): void;
    worldItemReference(worldItemReferenceId: string): ItemHandle;
}

Index

Properties

angularVelocity groupState id itemHandle itemTemplateId state useGravity velocity

Methods

Properties

angularVelocity

angularVelocity: Vector3

アイテムの角速度(グローバル座標)を取得・変更します。

MovableItemでない場合は0ベクトルを返します。物理挙動をするMovableItemでない場合、変更しようとすると例外になります。 Grab中などに行われた変更は無視されます。

`Beta`groupState

groupState: StateProxy

group stateへのアクセスを提供します。 state と同じようにread/writeアクセスが可能ですが、値はアイテムグループに所属する全てのアイテムで共有されます。

アイテムグループに所属していない場合、ClusterScriptErrorが発生します。

アイテムグループの詳細はドキュメントを参照してください。

`Readonly`id

id: string

空間内のアイテムを一意に表すIDの文字列表現です。アイテムのItemHandleに対するItemHandle.idが返す値と同じです。

`Readonly`itemHandle

itemHandle: ItemHandle

アイテムのItemHandleを返します。

`Readonly`itemTemplateId

itemTemplateId: ItemTemplateId | null

クラフトアイテムの元になっているアイテムテンプレートのIDです。ワールドアイテムの場合、この関数はnullを返します。 ClusterScript.createItem等で利用できます。

state

state: StateProxy

アイテムごとのstateへのアクセスを提供します。 read/writeアクセスが可能です。stateのプロパティへのアクセスにより、そのプロパティ名をkeyとしてstateへアクセスすることができます。

Example

未定義のプロパティをreadしたときはundefinedが初期値になります。

let v = $.state.exampleKey; // "exampleKey"というkeyの値を読み込む。1度も書き込んでいないとき、値はundefined
if (v === undefined) { v = 0.0; }
$.state.exampleKey = v + 1;

stateには Sendable 型の値を書き込み保存することができます。

具体的には、数値、文字列、boolean、Vector2、Vector3、Quaternion、PlayerHandle、ItemHandle、そしてそれらの配列と文字列をキーとしたobjectが利用可能です。

undefined などのSendableではない値を書き込もうとした場合、無視されます。この挙動は将来的に変更される可能性があります。

Example

$.state.exampleKey1 = 1; // numberを書き込む
$.state.exampleKey2 = "hello"; // stringを書き込む
$.state.exampleKey3 = true; // booleanを書き込む
$.state.exampleKey4 = { foo: "bar" }; // objectを書き込む
$.state.exampleKey5 = [1, 2, 3]; // arrayを書き込む
$.state.exampleKey6 = { // 複雑なオブジェクトを書き込む
  array: [1, 2, 3],
  object: { foo: "bar" },
};

Example

配列やオブジェクトなどをstateに反映させるためには再代入が必要です。

$.state.exampleKey = [1, 2, 3];
// $.state.exampleKey.push(4); // このように書いてもstateに反映されない

// このように書くとstateに反映される
const v = $.state.exampleKey;
v.push(4);
$.state.exampleKey = v;

useGravity

useGravity: boolean

このアイテムが、通常時に重力の影響を受けるかを取得・変更します。 Grab中などはアイテムは重力の影響を受けませんが、useGravityには影響がありません。

物理挙動をするMovableItemでない場合、falseを返します。物理挙動をするMovableItemでない場合、変更しようとすると例外になります。

velocity

velocity: Vector3

アイテムの速度(グローバル座標)を取得・変更します。

Methods

addForce

addForce(force: Vector3): void
アイテムの重心に、現在のPhysicsUpdate中で有効な力を加えます。 ClusterScript.onPhysicsUpdateのコールバック内部でのみ使用可能で、それ以外の箇所で呼び出すと例外になります。
Parameters
- force: Vector3
  力 (グローバル座標)
Returns void

addForceAt

addForceAt(force: Vector3, position: Vector3): void
アイテムの指定位置に、現在のPhysicsUpdate中で有効な力(グローバル座標)を加えます。 ClusterScript.onPhysicsUpdateのコールバック内部でのみ使用可能で、それ以外の箇所で呼び出すと例外になります。
Parameters
- force: Vector3
  力 (グローバル座標)
- position: Vector3
  力点 (グローバル座標)
Returns void

addImpulsiveForce

addImpulsiveForce(impulsiveForce: Vector3): void
アイテムの重心に撃力を加えます。重心以外に撃力を加えたい場合はClusterScript.addImpulsiveForceAtを使用してください。
Parameters
- impulsiveForce: Vector3
  撃力 (グローバル座標)
Returns void

addImpulsiveForceAt

addImpulsiveForceAt(impulsiveForce: Vector3, position: Vector3): void
アイテムの指定位置に撃力を加えます。
Parameters
- impulsiveForce: Vector3
  撃力 (グローバル座標)
- position: Vector3
  力点 (グローバル座標)
Returns void

addImpulsiveTorque

addImpulsiveTorque(impulsiveTorque: Vector3): void
アイテムの重心に角力積を加えます。
Parameters
- impulsiveTorque: Vector3
  角力積 (グローバル座標)
Returns void

addTorque

addTorque(torque: Vector3): void
アイテムの重心に、現在のPhysicsUpdate中で有効なトルクを加えます。 ClusterScript.onPhysicsUpdateのコールバック内部でのみ使用可能で、それ以外の箇所で呼び出すと例外になります。
Parameters
- torque: Vector3
  トルク (グローバル座標)
Returns void

audio

audio(itemAudioSetId: string): ApiAudio
アイテムのItemAudioSetListに含まれる、itemAudioSetIdに指定したidの音声を参照するApiAudioオブジェクトを返します。

ItemAudioSetListの詳細はドキュメントを参照してください
Parameters
- itemAudioSetId: string
Returns ApiAudio

audioLink

audioLink(): AudioLinkHandle
アイテムのAudioLinkHandleオブジェクトを返します。アイテムにはAudioLinkコンポーネントが付いている必要があります。クラフトアイテムや、AudioLinkコンポーネントのないアイテムの場合、AudioLinkHandleのメソッドの呼び出しは無視されます。

Returns AudioLinkHandle

callExternal

callExternal(
    endpointId: ExternalEndpointId,
    request: string,
    meta: string,
): void
空間の外部にリクエストを送信します。レスポンスはClusterScript.onExternalCallEndで受け取ります。この呼び出しを利用するためには、開発者自身が外部のサーバーを用意する必要があります。

外部通信機能についてはドキュメントの外部通信の説明もあわせて参照してください。

頻度の制限
callExternalの呼び出し自体には頻度の制限はありませんが、外部サーバーが応答可能な頻度である必要があります。高負荷で応答ができていないと思われる場合は、制限やお問い合わせさせていただく場合があります。

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

流量制御による制限
callExternalが動作するためには、流量制御による遅延が30秒以下である必要があります。制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。

容量の制限
requestやmetaがサイズ制限を超えている場合、ClusterScriptError (requestSizeLimitExceeded) が発生します。

設定
callExternalを利用するには、EndpointとVerify Tokenが必要です。 EndpointとVerify TokenはCreator Kitの 外部通信(callExternal)接続先URL から登録および作成できます。

Endpointで外部サーバーがリクエストを受け取るエンドポイントURLを指定します。 Endpointはアカウントごとに最大100個登録できます。

Verify Tokenは開発者自身がEndpointを管理していることを確認するために利用されます。 Verify Tokenはアカウントごとに最大2個登録できます。

利用方法
リクエストはそのアイテム・ワールドをアップロードしたアカウントに紐付く、endpointIdで指定されたエンドポイントに送信されます。

Cluster ScriptからcallExternalが呼ばれるたびに、エンドポイントに対してclusterのサーバーからHTTP POST呼び出しが行われます。 POSTに対するresponseに含まれるデータがonExternalCallEndに渡されます。エンドポイントが5秒のタイムアウトを超えても応答しない場合、またエラーを返した場合、失敗と判定されます。 clusterからエンドポイントに対するリトライは行いません。

エンドポイントの仕様
以下の形式でHTTP POSTに応答する必要があります。対応しているのはHTTP/1.1およびHTTP/2のみで、HTTP/3による呼び出しには対応していません。 HTTPもしくはHTTPSに対応していますが、公開時にはセキュリティ向上のためHTTPSの利用を推奨します。

リクエスト
```
{
  "request": "...100kB以下の文字列..."
}
```
レスポンス
```
{
  "verify": "...verify_token (Creator Kitで取得できます)...",
  "response": "...100kB以下の文字列..."
}
```
verifyフィールドには、アカウントに紐づくいずれかのVerify Tokenを指定してください。

以下の場合、不正な応答とみなし、callExternalは失敗として扱われます。
- responseフィールドが100kBを超えていた場合
- verifyフィールドにいずれかの有効なVerify Tokenが指定されていなかった場合
不正な応答などでEndpointの所有が確認できない場合はcallExternal APIの利用を制限させていただきます。高負荷で応答ができていないと思われる場合なども、同様に制限やお問い合わせさせていただく場合があります。

プライバシー
プレイヤーの個人情報に該当する情報をプレイヤーの同意なく外部に送信することは禁止されています。そのような利用が疑われる場合、callExternal APIの利用の制限や利用目的のお問い合わせをさせていただく場合があります。また、当社が不適切と判断した場合、予告なく利用を制限させていただく場合もあります。
Parameters
- endpointId: ExternalEndpointId
  送信先となる外部のサーバーを指定するEndpointのIDです。
- request: string
  100kB以下の文字列です。外部のサーバーに送信されます。
- meta: string
  100 byte以下の文字列です。複数のcallExternal呼び出しを識別するために利用できます。空文字や、同じ文字列を複数回指定しても問題ありません。
Returns void
callExternal(request: string, meta: string): void
送信先のエンドポイントを指定せずに空間の外部にリクエストを送信します。
リクエストはCreator Kitの旧バージョンの外部通信(callExternal)接続先URLで登録されたエンドポイントに送信されます。
Parameters
- request: string
  100kB以下の文字列です。外部のサーバーに送信されます。
- meta: string
  100 byte以下の文字列です。複数のcallExternal呼び出しを識別するために利用できます。空文字や、同じ文字列を複数回指定しても問題ありません。
Returns void
Deprecated
このAPIは Creator Kit v2.32.0 以降では非推奨です。
代わりに、ExternalEndpointIdを渡すClusterScript.callExternalのオーバーロードを利用してください。

clearVisiblePlayers

clearVisiblePlayers(): void
このアイテムを見ることができるプレイヤーの設定をクリアします。

クリアされた場合、Itemは全員に見える状況になります。

Returns void

computeSendableSize

computeSendableSize(arg: Sendable): number
データがItemHandle.sendで送信されるときのデータサイズを計算して、byte数を返します。

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

createItem

createItem(
    itemTemplateId: ItemTemplateId | WorldItemTemplateId,
    position: Vector3,
    rotation: Quaternion,
): ItemHandle
指定したアイテムを空間内に生成します。

itemTemplateId にItemTemplateIdを渡した場合、クラフトアイテムが生成されます。 itemTemplateId にWorldItemTemplateIdを渡した場合、ワールドアイテムが生成されます。ただし、クラフトアイテムからの呼び出しにおいて、 itemTemplateId にWorldItemTemplateIdを渡した場合、エラーになります。

原則、元のアイテムのオーナーが生成されたアイテムのオーナーになります。

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

クラフトアイテム生成時の挙動
クラフトアイテムが実際に生成されるまでには遅延があります。

生成されるクラフトアイテムのテンプレートの作者は以下のいずれかを満たす必要があります。
- このスクリプトを実行しているアイテムがクラフトアイテムであった場合、そのクラフトアイテムのテンプレートと作者が同じ
- このスクリプトを実行しているアイテムがワールドアイテムであった場合、現在の会場と作者が同じ
また、ベータアイテムを生成するためには、このスクリプトを実行しているアイテムがベータアイテムである、もしくはベータワールドのワールドアイテムである必要があります。

クラフトアイテムの生成は、以下のような要因で失敗する可能性があります。
- 生成できる条件を満たさないクラフトアイテムを生成しようとした場合。
- クラフト容量が500%を超えるような生成を行おうとした場合。
- アイテムの生成中に元のアイテムのオーナーが退出した場合。
クラフトアイテムの生成に失敗した場合、返り値の ItemHandle は指している先が存在しない状態になり、 ItemHandle.exists がfalseを返すようになります。

ワールドアイテム生成時の挙動
World Item Template Listで登録したワールドアイテムテンプレートを参照してアイテムを生成します。

クラフトアイテムからワールドアイテムを生成することはできません。

World Item Template Listで登録されていないIdを指定した場合や、World Item Templateが設定されていないIdを指定した場合は、ClusterScriptErrorが発生しcreateItemは失敗します。

ワールドアイテムの生成中に元のアイテムのオーナーが退出した場合、生成に失敗する可能性があります。

ワールドアイテムの生成に失敗した場合、返り値の ItemHandle は指している先が存在しない状態になり、 ItemHandle.exists がfalseを返すようになります。
Parameters
- itemTemplateId: ItemTemplateId | WorldItemTemplateId
  生成されるアイテムのTemplateId
- position: Vector3
  生成位置 (グローバル座標)
- rotation: Quaternion
  生成姿勢 (グローバル座標)
Returns ItemHandle
Example
以下の例では、アイテムが使用されるとプレイヤーの上空にマーカーのワールドアイテムを生成し、作成したプレイヤーのPlayerHandleを送っています。
```
$.onUse((isDown, player) => {
  if (!isDown) return;

  const markerPosition = player.getPosition();
  markerPosition.y += 2.5;

  const markerRotation = player.getRotation();

  const worldItemTemplateId = new WorldItemTemplateId("marker");
  const itemHandle = $.createItem(worldItemTemplateId, markerPosition, markerRotation);

  itemHandle.send("createdPlayer", player);
});
```
createItem(
    itemTemplateId: ItemTemplateId | WorldItemTemplateId,
    position: Vector3,
    rotation: Quaternion,
    option: CreateItemOption,
): ItemHandle
Beta
オプションを指定してアイテムを生成します。
Parameters
- itemTemplateId: ItemTemplateId | WorldItemTemplateId
  生成されるアイテムのTemplateId
- position: Vector3
  生成位置 (グローバル座標)
- rotation: Quaternion
  生成姿勢 (グローバル座標)
- option: CreateItemOption
  オプション値
Returns ItemHandle
Example
```
let itemHandle = $.createItem(templateId, position, rotation, { asMember: true });
```

destroy

destroy(): void
アイテム自身を破棄します。アイテムが実際に破棄されるまでに遅延があります。

destroyで破棄するアイテムは以下のいずれかを満たす必要があります。
- クラフトアイテムである
- クラフトアイテムでない場合、 Create Item Gimmick や Scriptable Item の ClusterScript.createItem で動的に生成されたアイテムである
destroyできないアイテムに対して呼び出した場合、ClusterScriptError (executionNotAllowed)が発生してdestroyは失敗します。現状では、ワールド設置アイテムをdestroyすることはできません。
Returns void

getGrabbingPlayer

getGrabbingPlayer(): PlayerHandle | null
Grabbable Item コンポーネントが付いているアイテムを掴んでいるプレイヤーの PlayerHandle を取得します。誰もアイテムを掴んでいない場合はnullを返します。

onGrab のコールバックの中で呼んだ場合、 isGrab がtrueのときは掴んでいるプレイヤーの PlayerHandle を返し、falseのときはnullを返します。

Returns PlayerHandle | null

getItemsNear

getItemsNear(position: Vector3, radius: number): ItemHandle[]
指定した球状の空間内に検知可能なコライダーが存在する自身を除くアイテムのハンドルの一覧を返します。検知可能なコライダーは、PhysicalShapeが付いているコライダー、OverlapSourceShapeが付いているコライダー、Shapeが付いていない物理衝突をするコライダーです。検知対象となるレイヤーはDefault, RidingItem, InteractableItem, GrabbingItemレイヤーです。

大量のコライダーが範囲に含まれる場合に、条件を満たしたすべてのItemHandleを取得できない場合があります。この場合、コンソールに警告メッセージが出力されます。
Parameters
- position: Vector3
  中心 (グローバル座標)
- radius: number
  半径
Returns ItemHandle[]
検知したアイテムのハンドルの配列 (順序は未定義)

getLatestComments

getLatestComments(count: number): Comment[]
直近に行われたコメントをcountで指定した件数だけ取得します。

countは最大100までの自然数でコメントの最大取得件数を指定できます。場合によっては過去のコメントが十分に取得できないことがあります。その場合、配列にはcount未満の個数のコメントが含まれます。

countは0以上100以下の範囲内に収められます。

コメントはおおよそ時刻の早い方から順に並んでいますが、順序が安定していることは保証されません。発言時刻が近いコメントは取得のたびに順序が入れ替わる可能性があります。

このAPIはイベント及びテスト用スペースのみで利用可能です。イベント及びテスト用スペース以外でこのAPIを利用すると空の配列を返します。
Parameters
- count: number
Returns Comment[]

getOverlaps

getOverlaps(): Overlap[]
このアイテムのOverlapDetectorShapeに重なっている、検知対象となる物体を取得します。検知対象となる物体は、PhysicalShapeが付いているコライダー、OverlapSourceShapeが付いているコライダー、Shapeが付いていない物理衝突をするコライダーです。このアイテム自身との重なりは含まれません。

このアイテムもしくは検知対象となる物体のどちらかは、MovableItemであるか、Rigidbodyが付いているか、CharacterControllerがついているか、プレイヤーであるかのいずれかを満たす必要があります。このアイテムのOverlapDetectorShapeが衝突判定するレイヤーが検知対象となります。アイテムの生成時点ですでに重なっていたり、重なっている状態で有効化された場合など、空間的には重なっている場合にもこのメソッドの返り値に含まれない場合があります。

Returns Overlap[]
Example
```
// 自分と重なっているプレイヤーを数える。
let set = new Set();
let overlaps = $.getOverlaps();
for (let overlap of overlaps) {
  if (overlap.handle?.type === "player") {
    let player = overlap.handle;
    set.add(player.id);
  }
}
$.log(`player count: ${set.size}`);
```

getOwner

getOwner(): PlayerHandle
Beta
アイテムのオーナーであるプレイヤーを取得します。オーナーについての詳細はドキュメントを参照してください。

Returns PlayerHandle

getOwnProducts

getOwnProducts(
    productId: string,
    players: PlayerHandle | PlayerHandle[],
    meta: string,
): void
プレイヤーがこのワールドで購入したワールド内商品の所持状況を非同期で取得します。取得した所持状況は ClusterScript.onGetOwnProductsに設定したcallbackに渡されます。

プレイヤーが対象の商品を購入したことがある場合、コールバックのownProductsに所持状況が渡されます。プレイヤーが対象の商品を購入したことがない場合、プレイヤーに対応するOwnProductは配列に含まれません。

頻度の制限
ワールド内商品の所持状況を取得できる頻度には制限があります。
- このスクリプトを実行しているアイテムがクラフトアイテムであった場合、ひとつのアイテムあたり5回/分
- このスクリプトを実行しているアイテムがワールドアイテムであった場合、ひとつのスペースあたり全てのワールドアイテムの合計で100回/分
瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。
Parameters
- productId: string
  取得する商品IDです。
- players: PlayerHandle | PlayerHandle[]
  所持状況を取得する対象のプレイヤーです。
- meta: string
  100 byte以下の文字列です。複数のgetOwnProducts呼び出しを識別するために利用できます。空文字や、同じ文字列を複数回指定しても問題ありません。
Returns void

getPlayersNear

getPlayersNear(position: Vector3, radius: number): PlayerHandle[]
指定した球状の空間内のコライダーが存在するプレイヤーのハンドルの一覧を返します。
Parameters
- position: Vector3
  中心 (グローバル座標)
- radius: number
  半径
Returns PlayerHandle[]
検知したプレイヤーのハンドルの配列 (順序は未定義)

getPosition

getPosition(): Vector3
アイテムの現在の位置を取得します。値はアイテムのあるグローバル座標系で返されます。

setPositionで指定された値ではなく、移動中のアイテムの位置が返されることに留意してください。

Returns Vector3

getRidingPlayer

getRidingPlayer(): PlayerHandle | null
Ridable Item コンポーネントが付いているアイテムに乗っているプレイヤーの PlayerHandle を取得します。誰もアイテムに乗っていない場合はnullを返します。

onRide のコールバックの中で呼んだ場合、 isGetOn がtrueのときは乗っているプレイヤーの PlayerHandle を返し、falseのときはnullを返します。

Returns PlayerHandle | null

getRotation

getRotation(): Quaternion
アイテムの現在の姿勢を取得します。値はアイテムのあるグローバル座標系で返されます。

setRotationで指定された値ではなく、移動中のアイテムの姿勢が返されることに留意してください。

Returns Quaternion

getStateCompat

getStateCompat(
    target: CompatGimmickTarget,
    key: string,
    parameterType: CompatParamType,
): Date | CompatSendable | undefined
Creator Kit 製ワールドで対象のメッセージを取得します。 Creator Kitのワールドに組み込まれたアイテムでしか利用できません。クラフトアイテムで実行した場合はエラーになります。
Parameters
- target: CompatGimmickTarget
  メッセージを取得する対象
  
  "this": このアイテムへのメッセージを取得します。
  
  "owner": このアイテムのオーナーへのメッセージを取得します。
  
  "global": Globalへのメッセージを取得します。
- key: string
  メッセージの識別子
- parameterType: CompatParamType
  メッセージの型
  
  "signal", "boolean", "float", "double", "integer", "vector2", "vector3" が利用できます。
Returns Date | CompatSendable | undefined
parameterType に "signal" を指定した場合、シグナルが通知された日時を Date として返します。
それ以外の場合、メッセージの値を返します。メッセージの値が存在する場合、それは数値, boolean, Vector2, Vector3 のうちいずれかです。
Example
```
// 自身のアイテムを対象に foo という識別子の boolean 型のメッセージを取得する。
$.getStateCompat("this", "foo", "boolean");
```

getUnityComponent

getUnityComponent(type: string): UnityComponent | null
このオブジェクトにアタッチされたUnityコンポーネントのハンドルを、型名を指定して取得します。 typeとして指定できるコンポーネント名については UnityComponent の説明を参照してください。

同じコンポーネントが複数アタッチされている場合、最初に見つかったコンポーネントのハンドルを返します。

このAPIはCreatorKitからアップロードしたワールドでのみ利用可能です。クラフトアイテムからはこのAPIは利用できません。
Parameters
- type: string
Returns UnityComponent | null
指定したコンポーネントが存在すればそのコンポーネントのハンドル、なければnull

humanoidAnimation

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

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

isEvent

isEvent(): boolean
このアイテムが置かれた空間がイベントかどうかを返します。

Returns boolean
イベントの場合はtrue、そうでなければfalse

log

log(v: any): void
vの内容をtoStringしたものをログに出力します。ログの末尾には[アイテムの名前]が付与されます。
Parameters
- v: any
Returns void

material

material(materialId: string): MaterialHandle
アイテムのItemMaterialSetListに含まれる、materialIdに指定したidのマテリアルを参照するMaterialHandleオブジェクトを返します。

ItemMaterialSetListの詳細はドキュメントを参照してください。
Parameters
- materialId: string
Returns MaterialHandle
Example
```
// Interactするとマテリアルの色が変わるアイテム
$.onInteract(() => {
  const mh = $.material("materialId");
  mh.setBaseColor(Math.random(), Math.random(), Math.random(), 1);
});
```

onCollide

onCollide(callback: (collision: Collision) => void): void
このアイテムが別の物体と衝突したタイミングで呼ばれるcallbackを設定します。アイテムは物理挙動をする必要があります。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (collision: Collision) => void
Returns void
Example
```
$.onCollide(collision => {
  if (collision.handle?.type === "player") {
    $.log("collide with a player.");
  }
});
```

onCommentReceived

onCommentReceived(callback: (comments: Comment[]) => void): void
コメントが送信されたときに呼ばれるコールバックを登録します。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

タイミングの問題で同一のコメントに対して重複してコールバックが呼ばれたり、コールバックが呼ばれない可能性があります。

また、2つ以上のコメントに対して一括でコールバックが呼ばれることがあります。

このAPIはイベント及びテスト用スペースのみで利用可能です。イベント及びテスト用スペース以外ではこのAPIによるコールバック登録は成功しますが、コールバックは呼ばれません。
Parameters
- callback: (comments: Comment[]) => void
Returns void

onExternalCallEnd

onExternalCallEnd(
    callback: (
        response: string | null,
        meta: string,
        errorReason: string | null,
    ) => void,
): void
ClusterScript.callExternalが完了した場合に呼ばれるcallbackを登録します。 callbackはcallExternalの成功時または失敗時に一回ずつ呼び出されます。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (response: string | null, meta: string, errorReason: string | null) => void
  response: 外部から取得したレスポンス。失敗した場合はnullです。 meta: callExternalの時に渡したものと同じ文字列です。errorReason: responseがnullの場合、失敗の理由。
Returns void

onGetOwnProducts

onGetOwnProducts(
    callback: (
        ownProducts: OwnProduct[] | null,
        meta: string,
        errorReason: string | null,
    ) => void,
): void
ClusterScript.getOwnProductsで要求したワールド内商品の所持状況を取得した際に呼ばれるcallbackを登録します。スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

プレイヤーが対象の商品を購入したことがある場合、callbackのownProductsに所持状況が渡されます。プレイヤーが対象の商品を購入したことがない場合、プレイヤーに対応するOwnProductは配列に含まれません。

ルーム種別による挙動の違い
テスト用のスペースで呼び出された場合、callback の ownProducts にはテスト用のスペースで行った商品購入などによる所持状況のみが渡されます。テスト用のスペースでの所持状況はそれ以外のスペースの所持状況とは別で管理されており、テスト用のスペースでの商品購入などはそれ以外のスペースの所持状況に影響を与えません。

イベント会場で呼び出された場合、 callback の ownProducts は常に空の配列が渡されます
Parameters
- callback: (
      ownProducts: OwnProduct[] | null,
      meta: string,
      errorReason: string | null,
  ) => void
  ownProducts: 取得に成功した商品の所持状況です。失敗した場合はnullです。 meta: getOwnProductsの時に渡したものと同じ文字列です。errorReason: responseがnullの場合、失敗の理由。
Returns void

onGiftSent

onGiftSent(callback: (gifts: GiftInfo[]) => void): void
イベント会場において、イベントに参加中のいずれかのプレイヤーがギフトを贈ったときに呼ばれるコールバックを登録します。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

イベント以外の空間でもコールバック登録は成功しますが、イベント以外の空間では、後述するテスト用の機能を使った場合を除いてコールバックは呼ばれません。

このコールバックは実際にギフトが贈られた順序とは異なる順序で呼ばれることがあります。また、2つ以上のギフトに対して一括でコールバックが呼ばれることがあります。

このコールバック機能は、スペースまたはワールドクラフト内でクラスターコインを使用せずにテストできます。詳細はスラッシュコマンドで、ギフトに関する項目を参照してください。
Parameters
- callback: (gifts: GiftInfo[]) => void
  gifts: 贈られたギフトの情報です。
Returns void
Example
```
// イベントで贈られたギフトについて、そのギフトを送信したプレイヤーの表示名を取得する
$.onGiftSent((gifts) => {
  let names = gifts.map(g => g.senderDisplayName);
});
```

onGrab

onGrab(
    callback: (
        isGrab: boolean,
        isLeftHand: boolean,
        player: PlayerHandle,
    ) => void,
): void
アイテムを掴む・手放すときに呼ばれるcallbackを登録します。アイテムにはGrabbableItemコンポーネントが付いている必要があります。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (isGrab: boolean, isLeftHand: boolean, player: PlayerHandle) => void
  isGrab = 掴んだときにtrue、手放したときにfalseになります。
  
  isLeftHand = 左手で掴んだときや左手で手放したときにtrue、右手で掴んだときや右手で手放したときにfalseになります。
  
  player = アイテムを掴んだ・手放したプレイヤーのハンドルです。
Returns void
Example
```
$.onGrab((isGrab, isLeftHand) => {
  if (isGrab) {
    if (isLeftHand) {
      $.log("grabbed by left hand.");
    } else {
      $.log("grabbed by right hand.");
    }
  }
});
```
アイテムを掴んだ・手放したプレイヤーのハンドルを取得できます。
```
// 掴んでいる間、移動速度を上げる。
$.onGrab((isGrab, isLeftHand, player) => {
  if (isGrab) {
    player.setMoveSpeedRate(2);
  } else {
    player.setMoveSpeedRate(1);
  }
});
```

onInteract

onInteract(callback: (player: PlayerHandle) => void): void
掴めないアイテムに「使う」動作をした際に呼ばれるcallbackを登録します。アイテムには1つ以上のColliderコンポーネントが付いている必要があります。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (player: PlayerHandle) => void
  player = アイテムにインタラクトしたプレイヤーのハンドルです。
Returns void
Example
```
$.onInteract(() => {
  $.log("interacted.");
});
```
アイテムにインタラクトしたプレイヤーのハンドルを取得できます。
```
// インタラクトしたプレイヤーをリスポーンさせる。
$.onInteract(player => {
  player.respawn();
});
```

onPhysicsUpdate

onPhysicsUpdate(callback: (deltaTime: number) => void): void
このアイテムの物理状態が更新されるタイミングで呼ばれるcallbackを設定します。 (UnityではFixedUpdateに対応します)

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (deltaTime: number) => void
Returns void
Example
```
// 1秒間上昇して2秒かけて落下する。
// RigidbodyのMassが1であることが想定されています。
$.onPhysicsUpdate(deltaTime => {
  let t = $.state.time ?? 0;
  t += deltaTime;
  if (t < 1) {
    $.addForce(new Vector3(0, 12, 0));
  } else if (t > 3) {
    t = 0;
  }
  $.state.time = t;
});
```

onPurchaseUpdated

onPurchaseUpdated(
callback: (player: PlayerHandle, productId: string) => void,
): void
スペース内のプレイヤーについて、ワールド内商品の所持状況が変化した際に呼ばれるcallbackを登録します。このcallbackを登録するだけでは何も起きません。 ClusterScript.subscribePurchaseによる商品の登録を行うことで、指定した商品IDに関してcallbackが呼び出されるようになります。

所持状況が変化した内容を取得するために、ClusterScript.getOwnProductsを利用できます。

一部の状況で、商品の所持状況が変化したにもかかわらずcallbackが呼ばれないことがあります。 onPurchaseUpdated以外の手段でもgetOwnProductを呼ぶことで、 callbackが呼ばれなかった場合や商品を既に購入したプレイヤーがスペースに入室した場合にも所持状況がワールドに反映されるように実装してください。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (player: PlayerHandle, productId: string) => void
  player = 商品の所持状況が変化したプレイヤーです。 productId = 対象の商品IDです。
Returns void

onReceive

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

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

optionの指定によって、 PlayerScript.sendTo から送信されたメッセージを受け取ることができます。 PlayerScript.sendTo から送信されたメッセージを受け取る場合は、引数の option を設定してください。

optionが未設定の場合、ItemHandle.sendからのメッセージのみ受け取ります。
- option.item が true の場合、ItemHandle.send から送信されたメッセージを受け取ります。
- option.item が false の場合、ItemHandle.send から送信されたメッセージを無視します。
- option.item が未設定の場合、ItemHandle.send から送信されたメッセージを受け取ります。
- option.player が true の場合、PlayerScript.sendTo から送信されたメッセージを受け取ります。
- option.player が false の場合、PlayerScript.sendTo から送信されたメッセージを無視します。
- option.player が未設定の場合、PlayerScript.sendTo から送信されたメッセージを無視します。
option.playerが未設定の場合の扱いはPlayerScript.onReceiveと異なります。 ClusterScript.onReceiveでは既存のスクリプトの互換性を破壊しないためにオプションが未設定の場合はPlayerScriptからのメッセージは受け取りません。

コールバックに渡される sender の値は ItemHandle または PlayerHandle です。この値の取り扱い方はScript Referenceトップページのハンドルも参照してください。
Parameters
- callback: (messageType: string, arg: Sendable, sender: ItemHandle | PlayerHandle) => void
  senderは送信元のアイテムまたはプレイヤーを表します。
- Optionaloption: { item: boolean; player: boolean }
  コールバックの登録のオプションです。受け取るメッセージの種類を指定できます。
Returns void
Example
```
// 送られたメッセージがdamageかhealのときに、ログを出力する。
$.onReceive((messageType, arg, sender) => {
  switch (messageType) {
    case "damage":
      $.log(`damage: ${arg}`);
      break;
    case "heal":
      $.log(`heal: ${arg}`);
      break;
  }
});
```
Example
```
// PlayerScriptからのattackメッセージを受け取りログを出力する。
$.onReceive((messageType, arg, sender) => {
  if (messageType === "attack") {
    if (sender instanceof ItemHandle) {
      $.log(`attack: ${arg}`);
    }
  }
}, { player: true });
```

onRequestGrantProductResult

onRequestGrantProductResult(
callback: (result: ProductGrantResult) => void,
): void
PlayerHandle.requestGrantProductで実施した商品付与の結果を取得した際に呼ばれるコールバックを登録します。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

ルーム種別による挙動の違い
テスト用のスペースで呼び出された際、callback引数 result.status は付与対象のプレイヤーが商品の販売者であることやプレイヤーの商品の所持状況に関わらず "Granted" を示しますが、実際には商品付与は実施されません。
Parameters
- callback: (result: ProductGrantResult) => void
  result = 商品付与の結果を示します。
Returns void

onRequestPurchaseStatus

onRequestPurchaseStatus(
    callback: (
        meta: string,
        status: PurchaseRequestStatus,
        errorReason: string | null,
        player: PlayerHandle,
    ) => void,
): void
PlayerHandle.requestPurchaseで要求したワールド内商品購入リクエストの結果を受け取ったときに呼ばれるcallbackを登録します。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (
      meta: string,
      status: PurchaseRequestStatus,
      errorReason: string | null,
      player: PlayerHandle,
  ) => void
  meta = PlayerHandle.requestPurchaseで指定したmeta文字列です。
  
  status = ワールド内商品購入の結果を示すステータスです。
  
  errorReason = status が PurchaseRequestStatus.Unknown 、 PurchaseRequestStatus.NotAvailable または PurchaseRequestStatus.Failed の場合、失敗理由を示す追加の情報を返します。 status がそれ以外の場合、 null を返します。
  
  player = ワールド内商品購入をリクエストされたプレイヤーです。
Returns void

onRide

onRide(callback: (isGetOn: boolean, player: PlayerHandle) => void): void
乗ることができるアイテムに乗る・降りるときに呼ばれるcallbackを登録します。アイテムにはRidableItemコンポーネントが付いている必要があります。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (isGetOn: boolean, player: PlayerHandle) => void
  isGetOn = 乗るときにtrue、降りるときにfalseになります。
  
  player = アイテムに乗った・降りたプレイヤーのハンドルです。
Returns void
Example
```
// プレイヤーが乗っている間だけ回転する。
$.onRide(isGetOn => {
  $.state.isRiding = isGetOn;
});

$.onUpdate(deltaTime => {
  if (!$.state.isRiding) return;
  let t = $.state.time ?? 0;
  t += deltaTime;
  $.state.time = t % 360;
  $.setRotation(new Quaternion().setFromEulerAngles(0, t, 0));
});
```
アイテムに乗った・降りたプレイヤーのハンドルを取得できます。
```
$.onRide((isGetOn, player) => {
  $.state.isRiding = isGetOn;
  $.state.player = isGetOn ? player : null;
});
```

onStart

onStart(callback: () => void): void
このアイテムが新たに空間に現れたとき、初めてonUpdateが実行される前に一度だけ呼ばれるcallbackを登録します。 onReceiveのcallbackも登録していた場合、onStartが呼び出された後に呼び出されます。

このアイテムが新たに空間に現れたときとは、以下のいずれかのことを指します。
- createItem及びcreateItemGimmickでアイテムが生成されたとき
- Creator Kit製ワールドで、スペースが新規で始まるとき
- ワールドクラフトで、アイテムを配置もしくはコピーにより新たに生成されたとき
スクリプトロード時に最後に登録したcallbackのみが有効になります。

詳細はonStartの呼び出しルールについてを参照してください
Parameters
- callback: () => void
Returns void

onSteer

onSteer(callback: (input: Vector2, player: PlayerHandle) => void): void
乗ることができるアイテムに乗っているプレイヤーの移動入力に対して呼ばれるcallbackを登録します。アイテムには RidableItem コンポーネントが付いている必要があります。また、アイテムにSteerItemTriggerコンポーネントが付いている場合、SteerItemTriggerコンポーネントの実行が優先され、このcallbackは呼ばれません。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

callback の input はユーザーがスティックやキーボードで入力した移動入力の値です。 input のベクトルの大きさは0以上1以下です。

左右の入力は x として表され、右方向が正です。前後の入力は y として表され、前方向が正です。
Parameters
- callback: (input: Vector2, player: PlayerHandle) => void
  input = 移動入力のベクトルです。
  
  player = アイテムを操作しているプレイヤーのハンドルです。
Returns void

onSteerAdditionalAxis

onSteerAdditionalAxis(
callback: (input: number, player: PlayerHandle) => void,
): void
乗ることができるアイテムに乗っているプレイヤーが追加入力を行ったときに呼ばれるcallbackを登録します。アイテムには RidableItem コンポーネントが付いている必要があります。また、アイテムにSteerItemTriggerコンポーネントが付いている場合、SteerItemTriggerコンポーネントの実行が優先され、このcallbackは呼ばれません。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

追加入力を行う方法はプレイヤーの端末環境によって異なります。いずれの方法でも、入力値は-1以上1以下の値を取ります。
- モバイル環境では、画面右下に表示される上下ボタンで入力します。
- デスクトップ環境では、スペースキー・左シフトキーでそれぞれ上下の入力を行います。
- VR環境では、右手コントローラーで上下の入力を行います。
Parameters
- callback: (input: number, player: PlayerHandle) => void
  input = 追加入力の値です。
  
  player = アイテムを操作しているプレイヤーのハンドルです。
Returns void

onTextInput

onTextInput(
callback: (text: string, meta: string, status: TextInputStatus) => void,
): void
PlayerHandle.requestTextInputで要求した文字列入力の応答を受け取ったときに呼ばれるcallbackを登録します。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (text: string, meta: string, status: TextInputStatus) => void
  text = プレイヤーが入力した文字列です。文字列のサイズは1000byte以下かつ文字数は250以下（ただしASCIIは1文字当たり0.5文字として換算します）です。
  
  meta = PlayerHandle.requestTextInputで指定したmeta文字列です。
  
  status = 文字列入力が成功したかどうかを示すステータスです。
Returns void
Example
```
$.onTextInput((text, meta, status) => {
  switch(status) {
    case TextInputStatus.Success:
      $.log(text);
      break;
    case TextInputStatus.Busy:
      // 5秒後にretryする
      $.state.should_retry = true;
      $.state.retry_timer = 5;
      break;
    case TextInputStatus.Refused:
      // 拒否された場合は諦める
      $.state.should_retry = false;
      break;
  }
});
```

onUpdate

onUpdate(callback: (deltaTime: number) => void): void
updateループ毎に呼ばれるcallbackを登録します。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (deltaTime: number) => void
Returns void
Example
```
// 10秒間隔でログを出力する。
$.onUpdate(deltaTime => {
    let t = $.state.time ?? 0;
    t += deltaTime;
    if (t > 10) {
        $.log("10 sec elapsed.");
        t -= 10;
    }
    $.state.time = t;
});
```

onUse

onUse(callback: (isDown: boolean, player: PlayerHandle) => void): void
掴んでいるアイテムに「使う」動作をしたときに呼ばれるcallbackを登録します。アイテムにはGrabbableItemコンポーネントが付いている必要があります。また、アイテムにUseItemTriggerコンポーネントが付いている場合、UseItemTriggerコンポーネントの実行が優先され、このcallbackは呼ばれません。

スクリプトのトップレベルでの呼び出しのみサポートされます。トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。
Parameters
- callback: (isDown: boolean, player: PlayerHandle) => void
  isDown = 「使う」動作を開始したときにtrue、終了したときにfalseになります。
  
  player = アイテムを使ったプレイヤーのハンドルです。
Returns void
Example
```
$.onUse(isDown => {
  $.log(`isDown: ${isDown}.`);
});
```
アイテムを使ったプレイヤーのハンドルを取得できます。
```
// 使ったプレイヤーに上方向の速度を加える。
$.onUse((isDown, player) => {
  if (isDown) {
    player.addVelocity(new Vector3(0, 5, 0));
  }
});
```

raycast

raycast(
    position: Vector3,
    direction: Vector3,
    maxDistance: number,
): RaycastResult | null

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

Parameters

position: Vector3
レイの原点 (グローバル座標)
direction: Vector3
レイの方向 (グローバル座標)
maxDistance: number
衝突判定を行う最大距離

Returns RaycastResult | null

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

Example

// アイテムのローカル座標系のZ軸正方向にレイを飛ばし、ヒットした一番近くの物体をログに出力する
let direction = new Vector3(0, 0, 1).applyQuaternion($.getRotation());
let result = $.raycast($.getPosition(), direction, 10);
if (result === null) {
  $.log("ray hits nothing");
} else if (result.handle === null) {
  $.log("ray hits something other than player or item");
} else if (result.handle.type === "player") {
  $.log("ray hits player " + result.handle.userDisplayName);
} else if (result.handle.type === "item") {
  $.log("ray hits item " + result.handle.id);
}

raycastAll

raycastAll(
    position: Vector3,
    direction: Vector3,
    maxDistance: number,
): RaycastResult[]

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

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

Parameters

position: Vector3
レイの原点 (グローバル座標)
direction: Vector3
レイの方向 (グローバル座標)
maxDistance: number
衝突判定を行う最大距離

Returns RaycastResult[]

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

Example

// 真下にレイを飛ばし、ヒットした一番近くのアイテムでもプレイヤーでもない座標にアイテム自身を移動する
let raycastResults = $.raycastAll($.getPosition(), new Vector3(0, -1, 0), 10);
let result = null;
let minDistance = Infinity;
for (let raycastResult of raycastResults) {
  if (raycastResult.handle !== null) continue;
  var distance = raycastResult.hit.point.clone().sub(pos).length();
  if (distance >= minDistance) continue;
  result = raycastResult;
  minDistance = distance;
}
if (result != null) {
  $.setPosition(result.hit.point);
}

requestOwner

requestOwner(player: PlayerHandle): void
Beta
アイテムのオーナーの変更をリクエストします。オーナーについての詳細はドキュメントを参照してください。

オーナーの変更には時間がかかる可能性があります。プレイヤーがアイテムを掴む、乗る、クラフトモードで操作する、またはスクリプトを編集している場合は、オーナーの変更は失敗します。また、対象のプレイヤーの通信状況や他のプレイヤーからのインタラクションなどの要因によって失敗する可能性があります。

頻度の制限
ひとつのアイテムは、最大で10回/秒までオーナーの変更をリクエストできます。瞬間的にこの制限を超えることはできますが、平均回数はこの制限を下回るようにしてください。制限を超えている場合、ClusterScriptError (rateLimitExceeded)が発生し操作は失敗します。
Parameters
- player: PlayerHandle
  新しくオーナーにするプレイヤー
Returns void

sendSignalCompat

sendSignalCompat(target: CompatStateTarget, key: string): void
Creator Kit 製ワールドで対象にシグナルを通知します。 Creator Kitのワールドに組み込まれたアイテムでしか利用できません。クラフトアイテムで実行した場合はエラーになります。
Parameters
- target: CompatStateTarget
  メッセージを通知する対象
  
  "this": このアイテムへメッセージを通知します。
  
  "owner": このアイテムのオーナーへメッセージを通知します。
- key: string
  メッセージの識別子
Returns void

setPlayerScript

setPlayerScript(playerHandle: PlayerHandle): void
アイテムのPlayerScriptコンポーネントが持つスクリプトをプレイヤーに登録します。アイテムにPlayerScriptコンポーネントがついていない場合は例外を投げます。

PlayerScriptコンポーネントの詳細はドキュメントを参照してください。

このアイテムが削除されると、スクリプトの登録は解除されます。同一のプレイヤーに対して複数回setPlayerScriptメソッドが呼ばれた場合、先に登録されていたスクリプトは削除され、最後に登録されたスクリプトだけが実行されます。

登録されたスクリプトからは、PlayerScript.sourceItemIdを使うことで、スクリプトを登録したアイテムの参照を取得することができます。

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

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

クラフトアイテムの PlayerScript
クラフトアイテムでは setPlayerScript はベータ機能です。
Parameters
- playerHandle: PlayerHandle
Returns void

setPosition

setPosition(v: Vector3): void
アイテムの移動させたい位置を指定します。値はアイテムのあるグローバル座標系で指定します。

アイテムにはMovableItemコンポーネントが付いている必要があります。位置はネットワークを介して補間して同期されるため、即座に反映されない場合があることに留意してください。
Parameters
- v: Vector3
Returns void

setRotation

setRotation(v: Quaternion): void
アイテムの回転させたい姿勢を指定します。値はアイテムのあるグローバル座標系で指定します。

アイテムにはMovableItemコンポーネントが付いている必要があります。姿勢はネットワークを介して補間して同期されるため、即座に反映されない場合があることに留意してください。
Parameters
- v: Quaternion
Returns void
Example
```
$.setRotation(new Quaternion().setFromEulerAngles(new Vector3(90, 0, 0)));
```

setStateCompat

setStateCompat(
    target: CompatStateTarget,
    key: string,
    value: CompatSendable,
): void
Creator Kit 製ワールドで対象にメッセージを通知します。 Creator Kitのワールドに組み込まれたアイテムでしか利用できません。クラフトアイテムで実行した場合はエラーになります。
Parameters
- target: CompatStateTarget
  メッセージを通知する対象
  
  "this": このアイテムへメッセージを通知します。
  
  "owner": このアイテムのオーナーへメッセージを通知します。
- key: string
  メッセージの識別子
- value: CompatSendable
  メッセージの値
  
  数値, boolean, Vector2, Vector3 が利用できます。
Returns void
Example
```
// 自身のアイテムを対象に foo という識別子で boolean型のメッセージを通知する。
$.setStateCompat("this", "foo", true);
```

setVisiblePlayers

setVisiblePlayers(players: PlayerHandle[]): void
このアイテムを見ることができるプレイヤーを設定します。

このメソッドを呼び出す前はItemは全員に見える設定です。

このメソッドを呼び出した場合、以前にこのメソッドで設定したアイテムを見ることのできるプレイヤーの設定は上書きされます。

変更されるのは見た目が見えるかどうかとInteract可能かの判定のみです。物理的な振る舞いや当たり判定は変更されません。

setVisiblePlayersとclearVisiblePlayersはアイテムに含まれるRendererのenabledを変更します。そのため、CreatorKitからアップロードしたワールドのアイテムに対してAnimator等を利用してRendererのenabledを変更する場合、この機能と合わせて使うと正常に動作しない可能性があります。

この設定を取り消すにはClusterScript.clearVisiblePlayersを利用してください。

引数のplayersがnullの場合は例外になります。引数で渡せるplayersの配列の要素数は最大で64個までです。
Parameters
- players: PlayerHandle[]
  アイテムを見れるようにするプレイヤーのリスト
Returns void

subNode

subNode(subNodeName: string): SubNode
アイテムの子要素に含まれる、subNodeNameに指定した名前のオブジェクトを参照するSubNodeオブジェクトを返します。 SubNode は子要素から再帰的に探索されます。

このメソッドでは Player Local UI がアタッチされたオブジェクトや、その子要素の参照はサポートされていません。これは、対象となるGameObjectの階層が自動で変更される場合があるためです。
Parameters
- subNodeName: string
Returns SubNode

subscribePurchase

subscribePurchase(productId: string): void
ClusterScript.onPurchaseUpdated で所持状況の変化を検知する商品を登録します。このAPIはスクリプトのトップレベルで呼び出すことはできません。
Parameters
- productId: string
  所持状況の変化を検知する商品のIDです。
Returns void

unsubscribePurchase

unsubscribePurchase(productId: string): void
ClusterScript.onPurchaseUpdated で所持状況の変化を検知する商品の登録を解除します。このAPIはスクリプトのトップレベルで呼び出すことはできません。
Parameters
- productId: string
  所持状況の変化を検知する商品のIDです。
Returns void

worldItemReference

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

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

スクリプトのトップレベルでの呼び出しとコールバックでの呼び出しの両方がサポートされます。
Parameters
- worldItemReferenceId: string
Returns ItemHandle
Example
```
// Interactすると指定したアイテムに "click" というメッセージを送信するアイテム
const target = $.worldItemReference("target");

$.onInteract(() => {
  target.send("click", null);
});
```

Interface ClusterScriptItem

Index

Properties

Methods

Properties

angularVelocity

BetagroupState

Readonlyid

ReadonlyitemHandle

ReadonlyitemTemplateId

state

Example

Example

Example

useGravity

velocity

Methods

addForce

Parameters

Returns void

addForceAt

Parameters

Returns void

addImpulsiveForce

Parameters

Returns void

addImpulsiveForceAt

Parameters

Returns void

addImpulsiveTorque

Parameters

Returns void

addTorque

Parameters

Returns void

audio

Parameters

Returns ApiAudio

audioLink

Returns AudioLinkHandle

callExternal

頻度の制限

流量制御

流量制御による制限

容量の制限

設定

利用方法

エンドポイントの仕様

プライバシー

Parameters

Returns void

Parameters

Returns void

Deprecated

clearVisiblePlayers

Returns void

computeSendableSize

Parameters

Returns number

createItem

クラフトアイテム生成時の挙動

ワールドアイテム生成時の挙動

Parameters

Returns ItemHandle

Example

Parameters

Returns ItemHandle

Example

destroy

Returns void

getGrabbingPlayer

Returns PlayerHandle | null

getItemsNear

Parameters

Returns ItemHandle[]

getLatestComments

Parameters

Returns Comment[]

getOverlaps

Returns Overlap[]

Interface ClusterScript`Item`

`Beta`groupState

`Readonly`id

`Readonly`itemHandle

`Readonly`itemTemplateId