External communication

External communication is a feature that allows you to exchange data between a server outside of Cluster and the space instance. It can be used with ItemScript.

The server must generally be managed by the creator themselves or by a trusted third party. Worlds and items created by the creator will communicate with the server registered by the creator. When external communication is initiated from a craft item, it accesses the server of the creator of that item.

Player privacy

External communication is a powerful feature that enables sending and receiving data between the space instance and an external server. To protect player privacy, external communication is carried out through Cluster’s servers.

To transmit personal information related to a player, player consent is required.

If it is suspected that personal information is being transmitted, we may inquire about its intended use. If we determine that the use is inappropriate, we may restrict usage without prior notice.

Preparing the server

The external communication server must provide an endpoint that accepts HTTP/HTTPS POST requests.

Each time the external communication API is called, an HTTP/HTTPS POST request will be sent to the endpoint. The data included in the response to the POST request will be passed to onExternalCallEnd. If the endpoint does not respond within the 5-second timeout or returns an error, the attempt is considered a failure. Cluster does not retry the request to the endpoint.

Request

{
  "request": "...string less than 100kB..."
}

Response

{
  "verify": "...verify_token...",
  "response": "...string less than 100kB..."
}

Verify Token

A Verify Token must be provided as verify. Verify Token is used by Cluster to confirm that the server is under the control of the creator. You can create a Verify Token by selecting “Cluster > External communication (callExternal) destination URL” from Creator Kit.

Since the token is only displayed once, make sure to copy and save it elsewhere.

A maximum of two tokens can be registered per account. To refresh the Verify Token, create a new Verify Token first, and update all Verify Tokens used by the servers before deleting the old Verify Token.

Verify Tokens are tied to an account. For all Endpoints tied to the same account, the same Verify Tokens can be used.

For high-load processes that may exceed 5 seconds, you can split the request from ClusterScript into a start-processing request and a result-checking request, and periodically check for results to ensure completion.

Endpoint registration

You can register the URL of the external communication server by selecting “Cluster > External communication (callExternal) destination URL” from Creator Kit.

Once the URL is registered, the Endpoint ID is displayed in the window. To specify the destination server in ClusterScript, create an ExternalEndpointId object based on the Endpoint ID and pass it to the callExternal API.

A maximum of 100 Endpoints can be registered per account.

In old versions of Creator Kit, only a single server endpoint could be registered per creator. For compatibility, if ExternalEndpointId object is not passed to callExternal API, the Endpoint with _legacy_single_endpoint ID is used.

If an Endpoint is deleted from Creator Kit, previously uploaded worlds and craft items will no longer be able to perform external communications using the deleted Endpoint ID.

Using the callExternal API

To perform external communication, use the following APIs: