ItemScript

ItemScriptはアイテム内で動作するスクリプトです。 ItemScriptの最も基本的な使い方は、$.onXXXXでプレイヤーの行動や周囲の環境の変化を取得し、それに対するアイテム自身の振る舞いを記述することです。

インタラクトすると音がなるItemScript

const sfx = $.audio("sfx1");

$.onInteract(() => {
  sfx.play();
});

また、$.onUpdate は特に変化が発生しなくても高頻度(通常は20FPS以上)で呼び出されます。

一定速度で移動するItemScript

$.onStart(() => {
  $.state.pos = $.getPosition();
});

$.onUpdate(dt => {
  const newPos = $.state.pos;
  newPos.x += dt;

  $.setPosition(newPos);
  $.state.pos = newPos;
});

これらの$.onXXXXに渡されている関数をコールバックと呼びます。

$.onXXXXは大まかに三種類に分けることができます。

プレイヤーのアクションや、外部の変化を取得するもの: onUse, onInteract, onCollide, onReceive など
決まったタイミングで呼び出されるもの: onStart, onUpdate など
時間のかかる処理の完了時に呼び出されるもの: onExternalCallEnd, onTextInput など

このように、アイテム単体でも自律的に振る舞う物体やNPCを記述することができます。

$.state

技術的理由により、ItemScriptはメモリー内の変数などの値を永続的に保持することができません。ひとつのコールバックの実行中はメモリーが保持されることが保証されていますが、複数のコールバック呼び出しの間ではメモリーは消去されうると想定する必要があります。このようなケースでは$.stateを使うことで状態を保持できます。

動かない例

let x = 0;
$.onUpdate(dt => {
    x += dt;
    $.setPosition(new Vector3(x, 0, 0));
});

動く例

$.onStart(() => {
    $.state.x = 0;
});

$.onUpdate(dt => {
    $.state.x = $.state.x + dt;
    $.setPosition(new Vector3($.state.x, 0, 0));
});

ItemScriptの設定と実行順序

ItemScriptはワールド設置アイテムかアイテムテンプレートに対して設定されます。 (つまり、同じアイテムテンプレートから生成されたアイテムで異なるItemScriptを実行することはできません。)

アイテムが空間インスタンス内に生成されたとき (ワールド設置アイテムの場合は空間インスタンスが生成された直後)から、アイテムごとにItemScriptが独立して開始します。以下の順序で処理が実行されます。

(アイテムの生成)
onStart
それ以外のコールバック (onUse, onUpdateなど)
(アイテムの消滅)

ワールドクラフトでのクラフトアイテムの生成タイミングは、プレイヤーが設置したとき、もしくはcreateItem APIによって生成されたときのみです。$.onStartコールバックはこれらの生成タイミングでのみ呼ばれます。

以下のケースでは$.onStartコールバックは呼ばれません。

既存のワールドクラフトを再開した場合: 0人の既存の空間インスタンスにプレイヤーが入っただけと見なされます
クラフトを投稿したワールドのスペースなどを作る場合: 既に存在するインスタンスのコピーにプレイヤーが入っただけと見なされます

ワールドクラフト内のアイテムは生成されてから1年以上持続することもあります。 $.onStartコールバックが呼ばれるのはその最初の一回のみです。

ItemScriptの内部動作

ItemScriptもアイテムそのものと同様にオーナーで実行されます。投機的実行を行うため、スクリプトそのものはアイテムが生成された後、全てのデバイスで読み込まれ評価されます。コールバックが実行されるのはオーナーと、オーナーになる予定のデバイスのみです。