English

流量制御の詳細

流量制御では、APIの呼び出しによって発生するデータの同期をコントロールします。 対象となるAPIのスペース全体での呼び出しに基づいて流量制御は行われます。

対象となるAPIを高頻度で使用した場合、流量制御による遅延が発生します。 流量制御による遅延が発生すると、APIの呼び出しからその影響が出るまでにかかる時間が長くなります。

現在の実装では、他のアイテム・プレイヤーの状態を変更するAPIに対して流量制御が行われます。 これらのAPIでは、サーバーを通じたデータの同期が行われています。 具体的な対象APIについては、スクリプトリファレンスの各APIの記述を参照してください。

流量制御による遅延が発生すると、データの同期にかかる時間が増加し、APIの呼び出しからその影響が出るまでにかかる時間が長くなります。

流量制御の全体像

サーバーを通じて同期されるデータの流量と量に基づいて、流量制御は行われます。 同期されるデータの流量とは、スペースに入っている全てのデバイスからの上記APIの呼び出しによって、1秒あたりに同期されるデータの量です。 同期されるデータの量・流量の具体的な計算方法については「同期されるデータの量・流量の計算方法」をご参照ください。

原則として、サーバーは100kB/sの流量でデータの同期を行います。

ただし、瞬間的に大きな流量が発生した場合、一度に1.5MBまでデータを同期することができます。 この方法で100kB/sの流量制限を超えた分の流量は累計超過量として蓄積されます。 累計超過量は、データの流量が100kB/sを下回った時に、その分だけ減少します。

累計超過量が1.5MBに達している場合、流量制御による遅延が発生します。 この場合、サーバーは100kB/sの流量でデータの同期を行います。

流量制御による遅延が発生すると、一時的にサーバー側にデータが蓄積され、データの同期が遅延します。 そのため、APIの呼び出しからその影響が出るまでにかかる時間が長くなります。

APIの呼び出し元と影響を受けるアイテム・プレイヤーが同じデバイス上で処理されている場合、流量制御の対象となりません。 この影響で、スペース内のオーナーの組み合わせによってワールドの挙動が変化する場合があります。 そのため、流量制御の挙動の確認は、複数端末を用いることを推奨しています。 詳細については「オーナーの組み合わせによる挙動の違い」をご参照ください。

流量制御による遅延発生時の挙動

流量制御による遅延が発生している場合、コンソールに警告が表示されます。 デベロッパーメニューにて「ログをすべて表示」が有効になっているとき、0.1秒以上の流量制御による遅延が発生している場合には、10秒ごとにコンソールに以下のような警告が表示されます。

ClusterMessageDelayWarning: a delay of 0.6 seconds has occurred (maximum delay limit: 30 seconds)

上記の例では、0.6秒の流量制御による遅延が発生しています。

流量制御による遅延が大きい場合に発生するエラー

以下のAPIは、流量制御による遅延の大きさが30秒以上であるときにエラーとなります。

  • ItemHandle.send
  • PlayerHandle.send
  • PlayerScript.sendTo

同期されるデータの量・流量の計算方法

同期されるデータの量はAPIによって異なりますが、どのAPIであっても1回の呼び出しにつき1250byte以下であることが保証されています。

また、 ItemHandle.send ・ PlayerHandle.send ・ PlayerScript.sendTo については、同期されるデータの量は エンコードされた arg のデータサイズ + 250 byte 以下であることが追加で保証されています。 ここでのエンコードされた arg のデータサイズとは、 ClusterScript.computeSendableSize ・ PlayerScript.computeSendableSize によって計算される値です。

同期されるデータの量を用いて、同期されるデータの流量も計算することができます。

同期されるデータの流量の計算例

たとえば、ItemHandle.send を1秒間に150回呼び出し、arg のデータサイズが200byteである場合、同期されるデータの流量は以下の式で計算される値以下であることが保証されます。

同期されるデータの流量 = (200 byte + 250 byte) × 150回/秒 = 67.5kB/秒

このとき、次節で説明するように、同期されるデータの流量は100kB/s以下であることにより、流量制御による遅延は発生しないことが保証されます。

流量制御に関する保証

サーバーによるデータの同期が100kB/sで行われることより、次のことが保証されます。

  • 任意の期間内で同期されるデータの流量が100kB/秒以下である限り、その期間が終わった時に、流量制御による遅延は発生・増加しません
  • 流量制御による遅延がない状態からであれば、一度に3MBの量のデータを同期したとしても、流量制御による遅延の大きさは30秒未満となります

また、上記に加えて、他のアイテム・プレイヤーの状態を変更するAPIの呼び出しが行われていない状態からであれば、一度に1.5MBの量のデータを同期したとしても、流量制御による遅延は発生しません。

オーナーの組み合わせによる挙動の違い

APIを呼び出すItemScript・PlayerScriptとAPIによる影響を受けるアイテム・プレイヤーが同じデバイス上で処理されている場合、流量制御による遅延の影響を受けません。 また、サーバーを通じて同期されるデータの量も0として扱われます。

同じデバイス上で処理が行われるのは次のような場合です。

  • APIを呼び出すItemScriptのアイテムのオーナーと、影響を受けるアイテムのオーナーが等しいもの
  • APIを呼び出すItemScriptのアイテムのオーナーと、影響を受けるプレイヤーのデバイスが等しいもの
  • APIを呼び出すPlayerScriptが実行されるデバイスと、影響を受けるアイテムのオーナーが等しいもの
  • APIを呼び出すPlayerScriptが実行されるデバイスと、影響を受けるプレイヤーのデバイスが等しいもの (自分自身に対してAPIを呼び出す場合)

また、これに伴い、関連するアイテムのオーナーが変化した場合、APIによる影響が発生する順番が逆転することがあります。