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.
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.
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.
Impulsive force (global coordinates)
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.
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.
Beta
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.
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));
});
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.
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.