Interface ClusterScriptItem

アイテムの重心に、現在のPhysicsUpdate中で有効な力を加えます。 onPhysicsUpdateのコールバック内部でのみ使用可能で、それ以外の箇所で呼び出すと例外になります。

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

アイテムの重心に撃力を加えます。 重心以外に撃力を加えたい場合はaddImpulsiveForceAtを使用してください。

アイテムの指定位置に撃力を加えます。

アイテムの重心に角力積を加えます。

アイテムの重心に、現在のPhysicsUpdate中で有効なトルクを加えます。 onPhysicsUpdateのコールバック内部でのみ使用可能で、それ以外の箇所で呼び出すと例外になります。

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

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

空間の外部にリクエストを送信します。 レスポンスは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の利用の制限や利用目的のお問い合わせをさせていただく場合があります。 また、当社が不適切と判断した場合、予告なく利用を制限させていただく場合もあります。

送信先のエンドポイントを指定せずに空間の外部にリクエストを送信します。
リクエストはCreator Kitの旧バージョンの外部通信(callExternal)接続先URLで登録されたエンドポイントに送信されます。

Deprecated

このAPIは Creator Kit v2.32.0 以降では非推奨です。
代わりに、 ClusterScript.callExternal(ExternalEndpointId, string, string) を利用してください。

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

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

データがsendで送信されるときのデータサイズを計算して、byte数を返します。

データがSendableではない場合はTypeErrorが発生します。

指定したアイテムを空間内に生成します。

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を返すようになります。

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);
});

オプションを指定してアイテムを生成します。

Example

let itemHandle = $.createItem(templateId, position, rotation, { asMember: true });

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

destroyで破棄するアイテムは以下のいずれかを満たす必要があります。

• クラフトアイテムである
• クラフトアイテムでない場合、 Create Item Gimmick や Scriptable Item の ClusterScript.createItem で動的に生成されたアイテムである

destroyできないアイテムに対して呼び出した場合、ClusterScriptError (executionNotAllowed)が発生してdestroyは失敗します。 現状では、ワールド設置アイテムをdestroyすることはできません。

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

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

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

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

Returns

検知したアイテムのハンドルの配列 (順序は未定義)

直近に行われたコメントをcountで指定した件数だけ取得します。

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

countが0より小さい場合や100より大きい場合は0~100の範囲に丸められます。

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

このAPIはイベント及びテスト用スペースのみで利用可能です。 イベント及びテスト用スペース以外でこのAPIを利用すると空の配列を返します。

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

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

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}`);

プレイヤーがこのワールドで購入したワールド内商品の所持状況を非同期で取得します。 取得した所持状況は ClusterScript.onGetOwnProductsに設定したcallbackに渡されます。

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

ワールド内商品の所持状況を取得できる頻度には制限があります。

• このスクリプトを実行しているアイテムがクラフトアイテムであった場合、ひとつのアイテムあたり5回/分
• このスクリプトを実行しているアイテムがワールドアイテムであった場合、ひとつのスペースあたり全てのワールドアイテムの合計で100回/分

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

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

指定した球状の空間内のコライダーが存在するプレイヤーのハンドルの一覧を返します。

Returns

検知したプレイヤーのハンドルの配列 (順序は未定義)

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

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

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

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

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

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

Creator Kit 製ワールドで対象のメッセージを取得します。 Creator Kitのワールドに組み込まれたアイテムでしか利用できません。 クラフトアイテムで実行した場合はエラーになります。

Example

// 自身のアイテムを対象に foo という識別子の boolean 型のメッセージを取得する。
$.getStateCompat("this", "foo", "boolean");

Returns

parameterType に "signal" を指定した場合、シグナルが通知された日時を Date として返します。
それ以外の場合、メッセージの値を返します。メッセージの値が存在する場合、それは数値, boolean, Vector2, Vector3 のうちいずれかです。

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

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

このAPIはCreatorKitからアップロードしたワールドでのみ利用可能です。 クラフトアイテムからはこのAPIは利用できません。

Returns

指定したコンポーネントが存在すればそのコンポーネントのハンドル、なければnull

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

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

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

Returns

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

vの内容をtoStringしたものをログに出力します。 ログの末尾には[アイテムの名前]が付与されます。

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

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

Example

// Interactするとマテリアルの色が変わるアイテム
$.onInteract(() => {
  const mh = $.material("materialId");
  mh.setBaseColor(Math.random(), Math.random(), Math.random(), 1);
});

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

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

Example

$.onCollide(collision => {
  if (collision.handle?.type === "player") {
    $.log("collide with a player.");
  }
});

コメントが送信されたときに呼ばれるコールバックを登録します。

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

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

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

このAPIはイベント及びテスト用スペースのみで利用可能です。 イベント及びテスト用スペース以外ではこのAPIによるコールバック登録は成功しますが、コールバックは呼ばれません。

callExternalが完了した場合に呼ばれるcallbackを登録します。 callbackはcallExternalの成功時または失敗時に一回ずつ呼び出されます。

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

ClusterScript.getOwnProductsで要求したワールド内商品の所持状況を取得した際に呼ばれるcallbackを登録します。 スクリプトのトップレベルでの呼び出しのみサポートされます。 トップレベルで複数回呼ばれた場合、最後の登録のみが有効です。

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

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

イベント会場で呼び出された場合、 callback の ownProducts は常に空の配列が渡されます

イベント会場において、イベントに参加中のいずれかのプレイヤーがギフトを贈ったときに呼ばれるコールバックを登録します。

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

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

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

このコールバック機能は、スペースまたはワールドクラフト内でクラスターコインを使用せずにテストできます。 詳細は スラッシュコマンド で、ギフトに関する項目を参照してください。

Example

// イベントで贈られたギフトについて、そのギフトを送信したプレイヤーの表示名を取得する
$.onGiftSent((gifts) => {
  let names = gifts.map(g => g.senderDisplayName);
});

アイテムを掴む・手放すときに呼ばれるcallbackを登録します。アイテムにはGrabbableItemコンポーネントが付いている必要があります。

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

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);
  }
});

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

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

Example

$.onInteract(() => {
  $.log("interacted.");
});

アイテムにインタラクトしたプレイヤーのハンドルを取得できます。

// インタラクトしたプレイヤーをリスポーンさせる。
$.onInteract(player => {
  player.respawn();
});

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

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

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;
});

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

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

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

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

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トップページの ハンドル も参照してください。

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 });

PlayerHandle.requestPurchaseで要求したワールド内商品購入リクエストの結果を受け取ったときに呼ばれるcallbackを登録します。

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

乗ることができるアイテムに乗る・降りるときに呼ばれるcallbackを登録します。アイテムにはRidableItemコンポーネントが付いている必要があります。

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

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;
});

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

このアイテムが新たに空間に現れたときとは、以下のいずれかのことを指します。

• createItem及びcreateItemGimmickでアイテムが生成されたとき
• Creator Kit製ワールドで、スペースが新規で始まるとき
• ワールドクラフトで、アイテムを配置もしくはコピーにより新たに生成されたとき

スクリプトロード時に最後に登録したcallbackのみが有効になります。

詳細はonStartの呼び出しルールについてを参照してください

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

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

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

左右の入力は x として表され、右方向が正です。 前後の入力は y として表され、前方向が正です。

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

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

追加入力を行う方法はプレイヤーの端末環境によって異なります。 いずれの方法でも、入力値は-1以上1以下の値を取ります。

• モバイル環境では、画面右下に表示される上下ボタンで入力します。
• デスクトップ環境では、スペースキー・左シフトキーでそれぞれ上下の入力を行います。
• VR環境では、右手コントローラーで上下の入力を行います。

PlayerHandle.requestTextInputで要求した文字列入力の応答を受け取ったときに呼ばれるcallbackを登録します。

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

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;
  }
});

updateループ毎に呼ばれるcallbackを登録します。

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

Example

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

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

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

Example

$.onUse(isDown => {
  $.log(`isDown: ${isDown}.`);
});

アイテムを使ったプレイヤーのハンドルを取得できます。

// 使ったプレイヤーに上方向の速度を加える。
$.onUse((isDown, player) => {
  if (isDown) {
    player.addVelocity(new Vector3(0, 5, 0));
  }
});

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

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);
}

Returns

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

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

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

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);
}

Returns

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

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

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

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

Creator Kit 製ワールドで対象にシグナルを通知します。 Creator Kitのワールドに組み込まれたアイテムでしか利用できません。 クラフトアイテムで実行した場合はエラーになります。

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

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

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

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

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

クラフトアイテムでは setPlayerScript はベータ機能です。

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

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

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

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

Example

$.setRotation(new Quaternion().setFromEulerAngles(new Vector3(90, 0, 0)));

Creator Kit 製ワールドで対象にメッセージを通知します。 Creator Kitのワールドに組み込まれたアイテムでしか利用できません。 クラフトアイテムで実行した場合はエラーになります。

Example

// 自身のアイテムを対象に foo という識別子で boolean型のメッセージを通知する。
$.setStateCompat("this", "foo", true);

このアイテムを見ることができるプレイヤーを設定します。

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

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

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

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

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

引数のplayersがnullの場合は例外になります。 引数で渡せるplayersの配列の要素数は最大で64個までです。

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

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

ClusterScript.onPurchaseUpdated で所持状況の変化を検知する商品を登録します。 このAPIはスクリプトのトップレベルで呼び出すことはできません。

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

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

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

スクリプトのトップレベルでの呼び出しとコールバックでの呼び出しの両方がサポートされます。

Example

// Interactすると指定したアイテムに "click" というメッセージを送信するアイテム
const target = $.worldItemReference("target");

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