日本語

Details of Flow Control

Flow Control manages the synchronization of data triggered by API calls, based on the call frequency across all devices in a space.

If the target APIs are used at a high frequency, Flow Control Delay may occur. These delays increase the time between when an API call is made and when its effects are reflected in the game.

Currently, Flow Control applies to APIs for Modifying the State of Other Items and Players. These APIs synchronize data via the server. For details on specific APIs affected, please refer to the script reference for each API.

When Flow Control Delay occurs, data synchronization time increases and API effects are delayed.

How Flow Control Delay is controlled

Flow Control is performed based on the flow rate and amount of data synchronized through the server. The flow rate refers to the amount of data synchronized per second by calls to the above APIs across all devices in the space. For details on calculating the amount and flow rate of synchronized data, see “Calculating the amount and flow rate of synchronized data.”

In principle, the server synchronizes data at a flow rate of 100kB/s.

However, if a large instantaneous flow of data occurs, the server can synchronize up to 1.5MB of data at once. Any amount of data synchronized beyond the 100kB/s flow rate will be counted as a cumulative overage. This cumulative overage decreases whenever the data flow rate falls below 100kB/s.

If the cumulative overage reaches 1.5MB, Flow Control Delay occurs. In this state, the server will continue to synchronize data at a flow rate of 100kB/s.

When Flow Control Delay occurs, data accumulates temporarily on the server side, resulting in synchronization delays. This leads to a longer interval between the time an API call is made and when its effects become noticeable.

If the API call source and the items or players affected by that call are processed on the same device, Flow Control does not apply. As a result, the behavior of the world can vary depending on the combination of item owners within the space. Therefore, it is recommended to verify the behavior of Flow Control using multiple devices. For more details, please refer to “Behavioral differences from owner combinations.”

Behavior when Flow Control Delay occurs

When Flow Control Delay occurs, a warning is displayed in the console. If “Show all logs” is enabled in the Developer Menu, and the delay exceeds 0.1 seconds, the following warning will appear in the console every 10 seconds:

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

In this example, Flow Control Delay of 0.6 seconds has occurred.

Errors that occur when Flow Control Delay becomes excessive

The following APIs will throw errors if Flow Control Delay exceeds 30 seconds:

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

Calculating the amount and flow rate of synchronized data

The amount of synchronized data depends on the API, but it is guaranteed to be 1250 bytes or less per call for all APIs.

Additionally, for ItemHandle.send, PlayerHandle.send, and PlayerScript.sendTo, the amount of synchronized data is guaranteed to be less than or equal to encoded arg data size + 250 bytes. The encoded arg data size can be calculated using ClusterScript.computeSendableSize or PlayerScript.computeSendableSize.

The flow rate of synchronized data can be calculated using the amount of synchronized data.

Example of flow rate calculation

For example, if ItemHandle.send is called 150 times per second and the data size of arg is 200 bytes, the flow rate of synchronized data is guaranteed to be up to:

Synchronized data flow rate = (200 bytes + 250 bytes) × 150 calls per second = 67.5 kB/s

In this case, as explained in the next section, since the flow rate of synchronized data is less than 100kB/s, Flow Control Delay will not occur.

Guarantees regarding Flow Control

Due to the server’s synchronization speed of 100kB/s, the following guarantees are provided:

  • As long as the flow rate of synchronized data is 100kB/s or less during any period, Flow Control Delay will not occur or worsen during that period
  • Starting from a state with no Flow Control Delay, even synchronizing 3MB of data at once will result in a delay of less than 30 seconds

Additionally, starting from a state with no API calls to APIs for Modifying the State of Other Items and Players, synchronizing 1.5MB of data at once does not cause Flow Control Delay.

Behavioral differences from owner combinations

When the ItemScript or PlayerScript calling an API and the affected item or player are processed on the same device, they are neither subject to nor affected by Flow Control Delay. In such cases, the amount of data synchronized through the server is treated as zero.

This occurs under the following conditions:

  • The owner of the item running the ItemScript is the same as the owner of the affected item
  • The owner of the item running the ItemScript is the same as the device of the affected player
  • The device running the PlayerScript is the same as the owner of the affected item
  • The device running the PlayerScript is the same as the device of the affected player (e.g., calling an API on oneself)

When ownership changes, the order of API effects may change accordingly.