Interface ClusterScript

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

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

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

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

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

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

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

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

空間の外部にリクエストを送信します。 レスポンスはonExternalCallEndで受け取ります。 この呼び出しを利用するためには、開発者自身が外部のサーバーを用意する必要があります。

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

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

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

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

設定: リクエストを受け取るendpoint (外部通信(callExternal)接続先URL) をCreator Kitから登録してください。 endpointはアカウントに紐付き、アカウントに対してひとつだけ設定できます。 リクエストはそのアイテム・ワールドをアップロードしたアカウントのendpointに送信されます。

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

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

リクエスト

{
  "request": "...1kB以下の文字列..."
}

レスポンス

{
  "verify": "...verify_token (Creator Kitで取得できます)...",
  "response": "...1kB以下の文字列..."
}

verifyフィールドは、開発者自身がendpointを管理していることを確認するために利用されます。 responseフィールドが1kBを超えていた場合、不正な応答とみなし、callExternalは失敗として扱われます。

不正な応答などでendpointの所有が確認できない場合はcallExternal APIの利用を制限させていただきます。 高負荷で応答ができていないと思われる場合なども、同様に制限やお問い合わせさせていただく場合があります。

プレイヤーの個人情報に該当する情報をプレイヤーの同意なく外部に送信することは禁止されています。 そのような利用が疑われる場合、callExternal APIの利用の制限や利用目的のお問い合わせをさせていただく場合があります。 また、当社が不適切と判断した場合、予告なく利用を制限させていただく場合もあります。

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

指定したアイテムを空間内に生成します。アイテムが実際に生成されるまでには遅延があります。

アイテムの生成は、負荷や権限など様々な理由で失敗する可能性があります。

生成されるアイテムのテンプレートは以下のいずれかを満たす必要があります。

• このスクリプトを実行しているアイテムがクラフトアイテムであった場合、そのアイテムのテンプレートと作者が同じ
• このスクリプトを実行しているアイテムがワールドアイテムであった場合、現在の会場と作者が同じ
• ベータアイテムである

クラフト容量が500%を超えるような生成は失敗します。

アイテムの生成に失敗した場合、返り値のItemHandleは指している先が存在しない状態になり、 ItemHandle.exists がfalseを返すようになります

アイテムが生成された時、このメソッドを呼び出した時点でのこのアイテムのオーナーが入室中であった場合、そのプレイヤーが生成されたアイテムのオーナーになります。

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

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

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

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

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

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

Returns

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

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

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

Example

// 自分と重なっているプレイヤーを数える。
let set = new Set();
let overlaps = $.getOverlaps();
for(let overlap of overlaps) {
  let player = overlap.object.playerHandle;
  if (player != null && !set.has(player.id)) {
    set.add(player.id);
  }
}
$.log(`player count: ${set.size}`);

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

Returns

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

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

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

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

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

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

Example

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

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

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

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

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

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

Example

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

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

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

Example

$.onCollide(collision => {
  if (collision.object.playerHandle != null) {
    $.log("collide with a player.");
  }
});

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

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

アイテムを掴む・手放すときに呼ばれる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;
});

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

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

ベータでは引数 option を指定できます。 ベータでない場合、option引数を設定するとエラーになります。

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からのメッセージは受け取りません。

ベータではない場合、ItemHandle.sendからのメッセージのみ受け取ります。

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 ItemId) {
      $.log(`attack: ${arg}`);
    }
  }
}, { player: true });

乗ることができるアイテムに乗る・降りるときに呼ばれる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を登録します。

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

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

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

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

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コンポーネントが付いている必要があります。

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

Example

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

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

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

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

Returns

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

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

Returns

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

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

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

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

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

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

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

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

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

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

Example

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

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

Example

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

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