Interface ClusterScript

Adds a force, valid during the current PhysicsUpdate, to the item's center of gravity. This can only be used inside the callback of onPhysicsUpdate. Calling it elsewhere will result in an exception.

Adds a force (in global coordinates), valid during the current PhysicsUpdate, to a specified point on the item. This can only be used inside the callback of onPhysicsUpdate. Calling it elsewhere will result in an exception.

Adds an impulsive force to the item's center of gravity. To apply impulsive force to points other than the center of gravity, use addImpulsiveForceAt.

Adds an impulsive force to a specified point on the item.

Adds an impulsive torque to the item's center of gravity.

Adds a torque, valid during the current PhysicsUpdate, to the item's center of gravity. This can only be used inside the callback of onPhysicsUpdate. Calling it elsewhere will result in an exception.

Locates an audio entry with the ID itemAudioSetId within the item's ItemAudioSetList, and returns an ApiAudio object referring to it.

For details on ItemAudioSetList, refer to the documentation.

Sends a request outside of the space. The response is received through onExternalCallEnd. To use this call, the developer themselves must prepare an external server.

There is a limit on how often callExternal can be called.

• If the item running this script is a craft item, 5 times per minute per item
• If the item running this script is a world item, a total of 100 times per minute per space for all world items

It is possible to momentarily exceed this limit, but please ensure the average number of calls stays below this limit. If the limit is exceeded, ClusterScriptError (rateLimitExceeded) occurs and the operation fails.

If the request or meta exceeds the size limit, ClusterScriptError (requestSizeLimitExceeded) will occur.

Setup: Register the endpoint (external communication (callExternal) connection URL) from Creator Kit to receive the requests. The endpoint is tied to the account and can be set only once per account. Requests are sent to the endpoint of the account that uploaded the item/world.

Each time callExternal is called from Cluster Script, an HTTP POST call is made from cluster's server to the endpoint. The data included in the response to the POST is passed to onExternalCallEnd. If the endpoint does not respond within 5 seconds timeout or returns an error, it is considered a failure. There are no retries from cluster to the endpoint.

Must respond to HTTP POST in the following format. Only HTTP/1.1 and HTTP/2 are supported, calls via HTTP/3 are not supported. Both HTTP and HTTPS are supported, but HTTPS is recommended for security reasons upon publication.

Request

{
  "request": "...string (1kB or less)..."
}

Response

{
  "verify": "...verify_token (can be obtained in Creator Kit)...",
  "response": "...string (1kB or less)..."
}

The verify field is used to confirm the developer themselves manages the endpoint. If the response field exceeds 1kB, it is considered an invalid response and callExternal is treated as a failure.

If the ownership of the endpoint cannot be confirmed due to an invalid response, etc., the use of the callExternal API may be restricted. Similarly, restrictions or inquiries may be made in cases where it is thought that responses are not being made due to high load.

Sending information that corresponds to personal information of players without their consent is prohibited. If such use is suspected, there may be restrictions on the use of the callExternal API or inquiries regarding the purpose of use. Also, if deemed inappropriate by us, we may restrict its use without notice.

Calculates the data size in bytes when the data is sent with send. If the data is not compatible with send, a TypeError will occur.

Creates the specified item in the current space. There may be a delay before the item is actually created.

Item creation can fail for various reasons, including processing load or permission issues.

The template of the item to be created must meet one of the following criteria:

• If the item executing this script is a Craft Item, it must have the same author as that item's template.
• If the item executing this script is a World Item, it must have the same author as the current Venue.
• It is a Beta item.

If the creation of an item would cause the Craft Item Capacity Usage to exceed 500%, createItem will fail.

If item creation fails, the returned ItemHandle will be in a state where it does not point to anything, and ItemHandle.exists will return false.

When an item is created through this method, the owner of the item that executes the createItem method will become the owner of the new item, provided they are present in the room at that time.

An item can be created up to 10 times per second. This can be exceeded momentarily, but please keep the average below this limit. If the limit is exceeded, a ClusterScriptError (rateLimitExceeded) error will occur and createItem will fail.

Destroys this item. There may be a delay before the item is actually destroyed.

This currently only works with Dynamic Items. If executed on items embedded into worlds, an ClusterScriptError (executionNotAllowed) error will occur and destroy will fail.

Returns an array of handles for items (excluding itself) that have detectable colliders within a specified spherical space. Detectable colliders are: colliders with a PhysicalShape, colliders with an OverlapSourceShape, and colliders without a Shape that can cause physics collisions. Detectable layers are: Default, RidingItem, InteractableItem, and GrabbingItem.

Returns

An array of handles for the detected items (order is undefined)

Returns an array of detectable objects that overlap with this item's OverlapDetectorShape. Detectable objects are: colliders with a PhysicalShape, colliders with an OverlapSourceShape, and colliders without a Shape that can cause physics collisions. Overlaps with this item itself are excluded.

Either this item or the detectable object must fulfill one of the following: be a MovableItem, have a Rigidbody, have a CharacterController, or be a player. Detectable layers are those that perform collision detection on this item's OverlapDetectorShape. In some cases, this method may exclude objects that do overlap in space, eg. if the item had already been overlapping when it was created or enabled.

Example

// Count players who overlap with me
let set = new Set();
let overlaps = $.getOverlaps();
for(let overlap of overlaps) {
  let player = overlap.object.playerHandle;
  if (player != null && !set.has(player.id)) {
    set.add(player.id);
  }
}
$.log(`Player count: ${set.size}`);

Returns an array of handles for players whose colliders exist within a specified spherical space.

Returns

An array of handles for the detected players (order is undefined)

Obtains the current position of the item. Values will be returned in the global coordinates of the world the item is in.

If you call this immediately after calling setPosition, please be aware it will return the item's current position, not the value passed to setPosition.

Obtains the current rotation of the item. Values will be returned in the global coordinates of the world the item is in.

If you call this immediately after calling setRotation, please be aware it will return the item's current rotation, not the value passed to setRotation.

In Worlds made using the Creator Kit, obtains a message from the target. If used outside of items in Creator Kit-developed worlds, a runtime error will occur.

Example

// Obtain a message to this item, with the identifer "foo", in the boolean type.
$.getStateCompat("this", "foo", "boolean");

Locates an animation entry with the ID humanoidAnimationId within the item's HumanoidAnimationList, and returns a HumanoidAnimation object referring to it.

For details on HumanoidAnimationList, refer to the documentation.

Performs a toString on the content of v, then outputs it to the log.

Returns a MaterialHandle object that references the material with the id specified in materialId in the item's ItemMaterialSetList.

For details on ItemMaterialSetList, see documentation.

Example

// Items that change the color of the material when interacted
$.onInteract(() => {
  const mh = $.material("materialId");
  mh.setBaseColor(new Color(Math.random(), Math.random(), Math.random(), 1));
});

Registers a callback to be called when this item collides with another object. The item must have physics behaviors enabled.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

$.onCollide(collision => {
  if (collision.object.playerHandle != null) {
    $.log("Collided with a player.");
  }
});

Registers a callback to be called upon the completion of callExternal. The callback is called once upon success or failure of callExternal.

Only supported for calls at the script's top level. If called multiple times at the top level, only the last registration is effective.

Registers a callback to be called when grabbing or releasing an object. The item must have a GrabbableItem Component attached.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

$.onGrab((isGrab, isLeftHand) => {
  if (isGrab) {
    if (isLeftHand) {
      $.log("Grabbed by left hand.");
    } else {
      $.log("Grabbed by right hand.");
    }
  }
});

The player handle can also be obtained.

// Increase the movement speed while grabbing
$.onGrab((isGrab, isLeftHand, player) => {
  if (isGrab) {
    player.setMoveSpeedRate(2);
  } else {
    player.setMoveSpeedRate(1);
  }
});

Registers a callback to be called when a "Use" action is performed on a non-grabbable item. The item must have 1 or more Collider Components attached.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

$.onInteract(() => {
  $.log("Interacted.");
});

The player handle can also be obtained.

// Respawn the player who interacted with it
$.onInteract(player => {
  player.respawn();
});

Registers a callback to be called when this item's physics state gets updated. (Corresponds to FixedUpdate in Unity)

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

// Rise for 1 second, then fall for 2 seconds.
// The Rigidbody's Mass here is assumed to be 1.
$.onPhysicsUpdate(deltaTime => {
  let t = $.state.time ?? 0;
  t += deltaTime;
  if (t < 1) {
    $.addForce(new Vector3(0, 12, 0));
  } else if (t > 3) {
    t = 0;
  }
  $.state.time = t;
});

Registers a callback to be called when this item receives a message sent from ItemHandle.send or sent from PlayerScript.sendTo to ItemId.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

In beta, the option argument can be specified. In non-beta, setting the option argument will result in an error.

By specifying option, it can receive messages sent from PlayerScript.sendTo. To receive messages sent from PlayerScript.sendTo, set the argument option.

If option is unset or not beta, it will only receive messages from ItemHandle.send.

• If option.item is true, then messages sent from ItemHandle.send will be received.
• If option.item is false, then messages sent from ItemHandle.send will be ignored.
• If option.item is unset, then messages sent from ItemHandle.send will be received.
• If option.player is true, the messages sent from PlayerScript.sendTo will be received.
• If option.player is false, then messages sent from PlayerScript.sendTo will be ignored.
• If option.player is unset, then messages sent from PlayerScript.sendTo will be ignored.

The handling of the case where option.player is unset is different from that of PlayerScript.onReceive. With ClusterScript.onReceive, it will not receive any messages from PlayerScript if the option is unset in order not to break compatibility of existing scripts.

If not beta, it will only receive messages from ItemHandle.send.

Example

// Log to output if the message type received is either "damage" or "heal".
$.onReceive((messageType, arg, sender) => {
  switch (messageType) {
    case "damage":
      $.log(`damage: ${arg}`);
      break;
    case "heal":
      $.log(`heal: ${arg}`);
      break;
  }
});

Example

// Receive "attack" messages from PlayerScript and output logs. (Beta)
$.onReceive((messageType, arg, sender) => {
  if (messageType === "attack") {
    if (sender instanceof ItemId) {
      $.log(`attack: ${arg}`);
    }
  }
}, { player: true });

Registers a callback to be called when mounting or dismounting a ridable item. The item must have a RidableItem Component attached.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

// Rotates only while the players is riding.
$.onRide(isGetOn => {
  $.state.isRiding = isGetOn;
});

$.onUpdate(deltaTime => {
  if (!$.state.isRiding) return;
  let t = $.state.time ?? 0;
  t += deltaTime;
  $.state.time = t % 360;
  $.setRotation(new Quaternion().setFromEulerAngles(0, t, 0));
});

The player handle can also be obtained.

$.onRide((isGetOn, player) => {
  $.state.isRiding = isGetOn;
  $.state.player = isGetOn ? player : null;
});

Registers a callback to be called once, before the first execution of onUpdate, when this item first appears in the space.

The item appearing in the space refers to any of the following situations:

• When an item is created with createItem or createItemGimmick
• In Creator Kit based worlds, when the space starts anew
• In World Craft, when an item is newly created by placing or copying

Only the last registered callback at script load time will be active.

For more details, see When onStart is called

Registers a callback to be called when this item receives a text input from the player, requested with PlayerHandle.requestTextInput.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

$.onTextInput((text, meta, status) => {
  switch(status) {
    case TextInputStatus.Success:
      $.log(text);
      break;
    case TextInputStatus.Busy:
      // Retry in 5 seconds
      $.state.should_retry = true;
      $.state.retry_timer = 5;
      break;
    case TextInputStatus.Refused:
      // Give up if refused
      $.state.should_retry = false;
      break;
  }
});

Registers a callback to be called on each update loop.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

// Output to log every 10 seconds
$.onUpdate(deltaTime => {
    let t = $.state.time ?? 0;
    t += deltaTime;
    if (t > 10) {
        $.log("10 seconds elapsed.");
        t -= 10;
    }
    $.state.time = t;
});

Registers a callback to be called when a "Use" action is performed on a item being grabbed. The item must have a GrabbableItem Component attached.

Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

Example

$.onUse(isDown => {
  $.log(`isDown: ${isDown}.`);
});

The player handle can also be obtained.

// Apply upwards velocity to the player who used this
$.onUse((isDown, player) => {
  if (isDown) {
    player.addVelocity(new Vector3(0, 5, 0));
  }
});

Casts a ray, and returns the first object it collided with.

Returns

The collided object (null if no collision)

Casts a ray, and returns all the objects it collided with.

Returns

An array of the collided objects (order is undefined)

In Worlds made using the Creator Kit, sends a signal to the target. If used outside of items in Creator Kit-developed worlds, a runtime error will occur.

Registers the scripts held by the item's Player Script component to the player. If the item does not have a PlayerScript component attached, an Error is thrown.

For more information on PlayerScript components, please refer to Documentation.

When this item is deleted, the script is unregistered. If the setPlayerScript method is called multiple times for the same player, the previously registered scripts are deleted and only the last registered script is executed.

In the registered script, you can use PlayerScript.sourceItemId to obtain a reference to the item which registered the script.

Specify a position to move the item to, using the global coordinates of the world the item is in.

The item must have a MovableItem Component attached. As the positions are interpolated and synced across the network, please be aware they may not be reflected immediately.

Specify a rotation to rotate the item to, using the global coordinates of the world the item is in.

The item must have a MovableItem Component attached. As the rotations are interpolated and synced across the network, please be aware they may not be reflected immediately.

Example

$.setRotation(new Quaternion().setFromEulerAngles(new Vector3(90, 0, 0)));

In Worlds made using the Creator Kit, sends a message to the target. If used outside of items in Creator Kit-developed worlds, a runtime error will occur.

Example

// Send a message to this item, with the identifier "foo", in the boolean type.
$.setStateCompat("this", "foo", true);

Locates an object named subNodeName within the item's children and descendants, and returns a SubNode object that refers to it.