ClusterScript

Overview of ClusterScript

ClusterScript is a script that allows you to control various aspects of items and players. The language is based on JavaScript, and it comes with several custom APIs.

Everything that exists in a space can be categorized into three types: items, players, and others.

There are two types of ClusterScripts:

ItemScript that runs within items
PlayerScript that runs within players

ItemScript is the more fundamental script. The actions performed by an ItemScript are automatically shared with everyone within the space instance. This applies to players who enter the space later as well.

PlayerScript operates within players. It can access the avatar of the player and low-level functions of the device they are using. It allows control over 2D overlay UI (PlayerLocalUI), which is only visible to that player. It can also execute processes for each graphics frame of the device.

Executing ClusterScript

ClusterScript runs independently for each item or player. ItemScript primarily describes the behavior of the item itself, while PlayerScript describes the behavior of the player. The internal information, such as JavaScript variables or $.state, cannot be directly accessed by other items or players' ClusterScripts. This helps ensure that items or scripts distributed by others can coexist without the need for modifications.

However, many use cases require physical collision detection or different processing for each player. Through various APIs, items and players can detect the presence of other items or players around them or within the space instance. Items are uniquely identified by an ItemHandle, and players are uniquely identified by a PlayerHandle. These are referred to as “handles.”

Other types, such as MaterialHandle and CameraHandle, also exist with “Handle” in their names. However, when we refer to “handle” in this document, we are typically only referring to the important ItemHandle and PlayerHandle.

To exchange information between ClusterScripts linked to different items or players, use the send() API with the destionation handle.

While various processes can be executed within ClusterScript, once a script finishes execution, its internal information is lost. To retain data beyond the lifespan of an item or player or to exchange data across space instances, you can use save data or external communication as described in Data management.

Beta API

ClusterScript contains many beta features. APIs marked with a beta flag in the ClusterScript Reference are considered beta APIs.

If you use a beta API in a world or item where beta is not enabled, a ClusterScriptError will occur within the script.