Class ItemHandleItem

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

Rate limitations

An item can manipulate other handles 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 the operation will fail.

Adds an impulsive force to a specified position on the item. This is ignored if the item is immune to force. There is no need for a PhysicalShape nor a mesh to be present on the point to apply the force.

Rate limitations

An item can manipulate other handles 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 the operation will fail.

Adds an impulsive torque to the item's center of gravity. This is ignored if the item is immune to force.

Rate limitations

An item can manipulate other handles 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 the operation will fail.

If the item exists, returns true. Note that this may return true even if it is currently loading.

Sends a message to an item. The item at the receiving end is expected to run a callback set using ClusterScript.onReceive. For data types that can be used as the message's payload (the arg argument), refer to Sendable.

Messages sent to destroyed items or invalid ItemHandles will be ignored.

Example

The below example sends a message that corresponds to the example code on ClusterScript.onReceive.

itemHandle.send("damage", 20);
itemHandle.send("heal", 10);

The below example sends a message with the message type chase, containing the handle of the player who used the item, to all items within a 2 meter radius.

$.onUse((isDown, player) => {
  if (!isDown) return;
  let items = $.getItemsNear($.getPosition(), 2);
  for (let item of items) {
    item.send("chase", player);
  }
});

The actions an item should do upon receiving a message should be written in that item's ClusterScript.onReceive. In the below example, the item will chase the player for 5 seconds.

$.onReceive((messageType, arg, sender) => {
  switch (messageType) {
    case "chase":
      $.state.target = arg;
      $.state.time = 0;
      break;
  }
});

$.onUpdate(deltaTime => {
  let target = $.state.target;
  if (!target) return;

  let time = $.state.time ?? 0;
  time += deltaTime;
  $.state.time = time;

  if (time > 5) {
    $.state.target = null;
    return;
  }

  $.setPosition($.getPosition().lerp(target.getPosition(), 0.02));
});

Rate limitations

An item can send messages 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 send will fail.

Size limitations

Encoded size of arg must be 1000 byte or less. If the data size exceeds the limit, a warning will be displayed. The data size can be calculated with computeSendableSize.

If the data size significantly exceeds the limit, ClusterScriptError (requestSizeLimitExceeded) will occur and the send will fail.