A handle to externally manipulate items. A handle may refer to itself, but it may also refer to others, or to nothing.

Hierarchy

  • ItemHandle

Properties

id: string

The string representation of the ID that uniquely identifies an item within the space. ItemHandles sharing an identical id will all refer to the same object.

Methods

  • Beta

    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.

    Parameters

    • force: Vector3

      Impulsive force (global coordinates)

    Returns void

  • Beta

    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.

    Parameters

    • impulse: Vector3

      Impulsive force (global coordinates)

    • position: Vector3

      Point to apply impulsive force (global coordinates)

    Returns void

  • Beta

    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.

    Parameters

    • torque: Vector3

      Impulsive torque (global coordinates)

    Returns void

  • Beta

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

    Returns boolean

  • 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.

    Parameters

    • messageType: string

      A short string to describe the message type

    • arg: Sendable

      The message payload

    Returns void

Generated using TypeDoc