Item Readonly idThe 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.
Readonly typeReturns string "item". This value can be used to distinguish ItemHandle and PlayerHandle.
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.
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.
When APIs for Modifying the State of Other Items and Players, including this API, are called excessively frequently beyond the limit within a space, the results may be applied with significant delays. For more details, please refer to Flow Control.
Impulsive force (global coordinates)
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.
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.
When APIs for Modifying the State of Other Items and Players, including this API, are called excessively frequently beyond the limit within a space, the results may be applied with significant delays. For more details, please refer to Flow Control.
Adds an impulsive torque to the item's center of gravity. This is ignored if the item is immune to force.
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.
When APIs for Modifying the State of Other Items and Players, including this API, are called excessively frequently beyond the limit within a space, the results may be applied with significant delays. For more details, please refer to Flow Control.
Impulsive torque (global coordinates)
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.
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));
});
There is a limit on how often send can be called.
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.
When APIs for Modifying the State of Other Items and Players, including this API, are called excessively frequently beyond the limit within a space, the results may be applied with significant delays. For more details, please refer to Flow Control.
If the item running this script is a world item, the send operation will only succeed if Flow Control Delay is 30 seconds or less.
If the limit is exceeded, ClusterScriptError (rateLimitExceeded) occurs and the operation fails.
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.
A short string to describe the message type
The message payload
Generated using TypeDoc
A handle to externally manipulate items. A handle may refer to itself, but it may also refer to others, or to nothing.