Item
Beta
angularGets or sets this item's angular velocity (global coordinates).
If this item is not a MovableItem
, the value will be a Zero Vector.
If this item is not a physics-enabled MovableItem
, attempting to modify it will result in an exception.
Changes made during grabbing, etc. will be ignored.
Readonly
idThe string representation of the ID that uniquely identifies an item within the space. This is the same as the ItemHandle.id of the ItemHandle for this item.
Readonly
itemReturns the ItemHandle that represents this item.
Readonly
Beta
itemThe ID of item template that this Craft Item is based on.
if the item executing this script is World Item, this function returns null
.
This value can be used by createItem.
Provides access to the state
of individual items.
Arbitrary property names can be used as keys for reading/writing data in the state
.
Reading from a not yet defined property will default to returning undefined
.
let v = $.state.exampleKey; // Read the value of the key "exampleKey". If it has never been written to before, it will return undefined.
if (v == null) { v = 0.0; }
$.state.exampleKey = v + 1;
Values of the Sendable type can also be written and saved to states.
Specifically, you can use numbers, strings, booleans, Vector2, Vector3, Quaternion, PlayerHandle, ItemHandle, arrays of the aforementioned types, and objects having keys assigned with strings.
$.state.exampleKey1 = 1; // Write a number
$.state.exampleKey2 = "hello"; // Write a string
$.state.exampleKey3 = true; // Write a boolean
$.state.exampleKey4 = { foo: "bar" }; // Write an object
$.state.exampleKey5 = [1, 2, 3]; // Write an array
$.state.exampleKey6 = { // Write a complex object
array: [1, 2, 3],
object: { foo: "bar" },
};
To make changes on arrays and objects reflect on a state
, they need to be reassigned.
$.state.exampleKey = [1, 2, 3];
// $.state.exampleKey.push(4); // This will NOT make the changes reflect on the state
// This will make the changes reflect on the state
const v = $.state.exampleKey;
v.push(4);
$.state.exampleKey = v;
Beta
useGets or sets whether this item is affected by gravity under normal conditions.
Items are not affected by gravity while being grabbed, but this does not affect useGravity
.
If this item is not a physics-enabled MovableItem
, the value will be false
.
If this item is not a physics-enabled MovableItem
, attempting to modify it will result in an exception.
Beta
velocityGets or sets this item's velocity (global coordinates).
If this item is not a MovableItem
, the value will be a Zero Vector.
If this item is not a physics-enabled MovableItem
, attempting to modify it will result in an exception.
Changes made during grabbing, etc. will be ignored.
Beta
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.
Force (global coordinates)
Beta
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.
Beta
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.
Impulsive force (global coordinates)
Beta
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.
Torque (global coordinates)
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.
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.
A string less than 1kB. It is sent to an external server.
A string less than 100 bytes. It can be used to identify multiple callExternal calls. It is fine to specify an empty string or the same string multiple times.
Beta
Creates the specified item in the current space.
If ItemTemplateId is passed as itemTemplateId
, a craft item will be created.
If WorldItemTemplateId is passed as itemTemplateId
, a world item will be created.
However, if WorldItemTemplateId
is passed to itemTemplateId
in a call from a craft item, an error will occur.
In principle, the owner of the item that executes the createItem
method will become the owner of the newly created item.
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.
There may be a delay before the craft item is actually created.
Craft item creation can fail for various reasons, including processing load or permission issues.
The template of the craft item to be created must meet one of the following criteria:
If the creation of an craft item would cause the Craft Item Capacity Usage to exceed 500%, createItem
will fail.
If craft item creation fails, the returned ItemHandle
will be in a state where it does not point to anything, and ItemHandle.exists will return false
.
Creates a world item by referring to the World Item Template List registered World Item Template.
It is not possible to create any world items from craft items.
If an unregistered Id in the World Item Template List or an Id without a World Item Template is specified, ClusterScriptError will occur and createItem
will fail.
If the owner of the original item exits during the creation of a world item, the creation may fail.
If world item creation fails, the returned ItemHandle
will be in a state where it does not point to anything, and ItemHandle.exists will return false
.
In the example below, when the item is used, a world item "marker" is created above the player, and the PlayerHandle
of the player who used the item is sent.
$.onUse((isDown, player) => {
if (!isDown) return;
const markerPosition = player.getPosition();
markerPosition.y += 2.5;
const markerRotation = player.getRotation();
const worldItemTemplateId = new WorldItemTemplateId("marker");
const itemHandle = $.createItem(worldItemTemplateId, markerPosition, markerRotation);
itemHandle.send("createdPlayer", player);
});
TemplateId
of the item to be created
Initial position (global coordinates)
Initial rotation (global coordinates)
Destroys this item. There may be a delay before the item is actually destroyed.
Items to destroy must meet one of the following criteria:
If called on an item that cannot be destroyed, a ClusterScriptError (executionNotAllowed
) error will occur and destroy
will fail.
Currently, it is not possible to destroy World Placed Items.
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
.
When a large number of colliders are included in the range, it may not be possible to retrieve all ItemHandles that meet the condition. In this case, a warning message will be output to the console.
An array of handles for the detected items (order is undefined)
Center position (global coordinates)
Radius of sphere
Beta
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.
// 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}`);
Asynchronously retrieves the status of owned purchasable items purchased by the player in this world. The retrieved status of owned purchasable items is passed to the callback set in ClusterScript.onGetOwnProducts.
If the player has purchased the specified item, the status of owned purchasable items will be included in the ownProducts
of the callback.
If the player has not purchased the specified item, the corresponding OwnProduct
for the player will not be included in the array.
There is a limit on how often getOwnProducts 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.
The product ID for the targe purchasable item.
A list of players whose status of owned purchasable items is to be retrieved.
A string less than 100 bytes. It can be used to identify multiple getOwnProducts calls. It is fine to specify an empty string or the same string multiple times.
Returns an array of handles for players whose colliders exist within a specified spherical space.
An array of handles for the detected players (order is undefined)
Center position (global coordinates)
Radius of sphere
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.
// Obtain a message to this item, with the identifer "foo", in the boolean type.
$.getStateCompat("this", "foo", "boolean");
The target from which to obtain messages
"this": Obtain a message for this item.
"owner": Obtain a message for this item's owner.
"global": Obtain a global message.
Message identifier
Message type
Can be one of the following: "signal", "boolean", "float", "double", "integer", "vector2", and "vector3".
Beta
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.
Beta
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.
// Items that change the color of the material when interacted
$.onInteract(() => {
const mh = $.material("materialId");
mh.setBaseColor(Math.random(), Math.random(), Math.random(), 1);
});
Beta
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.
$.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.
response: The response obtained from external. It is null in case of failure. meta: The same string passed during callExternal. errorReason: The reason for failure if response is null.
Registers a callback that is called when retrieving the status of owned purchasable items requested in ClusterScript.getOwnProducts. 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.
The status of owned purchasable items will be provided in the ownProducts
of the callback if the player has purchased the specified item.
The OwnProduct
will not be included in the array if the player has not purchased the specified item.
When called in a test space, the 'ownProducts' in the callback will only include the status of owned purchasable items resulting from item purchases made within that test space. Status of owned purchasable items in the test space is managed separately from other space, and item purchases in the test space do not affect status of owned purchasable items in other space.
Called in an event, the ownProducts
in the callback will always be an empty array.
response: The status of owned purchasable items of the successfully retrieved item. It is null in case of failure. meta: The same string passed during getOwnProducts. errorReason: The reason for failure if response is null.
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.
$.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);
}
});
isGrab = true
when grabbing, false
when releasing.
isLeftHand = true
when grabbed/released with the left hand, false
when with the right hand.
player = The handle of the player who grabbed/released the item.
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.
$.onInteract(() => {
$.log("Interacted.");
});
The player handle can also be obtained.
// Respawn the player who interacted with it
$.onInteract(player => {
player.respawn();
});
player = The handle of the player who interacted with the item.
Beta
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.
// 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 that is called when the status of owned purchasable items changes for players within the space. Simply registering this callback will not trigger any actions. Registering the product ID with ClusterScript.subscribePurchase, the callback will be invoked for the specified product ID.
ClusterScript.getOwnProducts can be used to retrieve the details of changes in status of owned purchasable items.
In some situations, the callback may not be called even though the status of owned purchasable items has changed.
Script should be implemented so that the status of owned purchasable items is reflected in the world by using methods like getOwnProduct
, even in cases where the callback was not called or when a player who has already purchased the item enters the space.
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.
player = The player whose status of owned purchasable items has changed. productId = The product ID of the target purchasable item.
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.
option.item
is true
, then messages sent from ItemHandle.send will be received.option.item
is false
, then messages sent from ItemHandle.send will be ignored.option.item
is unset, then messages sent from ItemHandle.send will be received.option.player
is true
, the messages sent from PlayerScript.sendTo will be received.option.player
is false
, then messages sent from PlayerScript.sendTo will be ignored.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.
// 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;
}
});
// 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 });
sender represents the sender ItemHandle or the sender PlayerHandle.
Optional
option: { item: boolean; player: boolean }(beta) Option to register callbacks. You can specify the type of messages to receive.
Registers a callback to be called when this item receives the result of the purchasable item purchase, requested with PlayerHandle.requestPurchase.
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.
meta = The meta string as specified in PlayerHandle.requestPurchase.
status = Status signifying the outcome of the purchasable item purchase.
errorReason = The reason for the failure is provided if the status is PurchaseRequestStatus.Unknown, PurchaseRequestStatus.NotAvailable, or PurchaseRequestStatus.Failed. If the status is anything else, it is null.
player = The player who was requested to purchase the purchasable item.
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.
// 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;
});
isGetOn = true
when mounting, false
when dismounting.
player = The handle of the player mounted/dismounted the item.
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:
createItem
or createItemGimmick
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.
$.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;
}
});
text = Text entered by the player.
meta = The meta string as specified in PlayerHandle.requestTextInput.
status = Status signifying the outcome of the text input request.
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.
// 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.
$.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));
}
});
isDown = true
when beginning the "Use" action, false
when ending.
player = The handle of the player who used the item.
Beta
Casts a ray, and returns the first object it collided with.
The collided object (null
if no collision)
Beta
Casts a ray, and returns all the objects it collided with.
When a large number of colliders are included in the range, it may not be possible to retrieve all ItemHandles that meet the condition. In this case, a warning message will be output to the console.
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.
The target to send the message
"this": Send a message to this item.
"owner": Send a message to this item's owner.
Message identifier
Beta
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.
$.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.
// Send a message to this item, with the identifier "foo", in the boolean type.
$.setStateCompat("this", "foo", true);
The target to send the message
"this": Send a message to this item.
"owner": Send a message to this item's owner.
Message identifier
Message value
Beta
Sets the players who can see this item.
Before calling this method, the Item is set to be visible to everyone.
If this method is called, the settings for which players can see the item set with this method will be overwritten.
The only things that change are whether or not the item is visible and whether or not it can be interacted with. The physical behavior and collision detection are not changed.
setVisiblePlayers
and clearVisiblePlayers
change the enabled property of the Renderer contained in the item.
Therefore, if you are using an Animator or other method to change the enabled state of a Renderer contained in an item in a world uploaded from Creator Kit, this function may not work properly if used in conjunction with it.
To cancel this setting, use ClusterScript.clearVisiblePlayers.
If the players argument is null, an exception will be thrown. The maximum number of elements in the array of players that can be passed as an argument is 64.
List of players who will be able to see the item
Registers a purchasable item in ClusterScript.onPurchaseUpdated for detecting changes in status of owned purchasable items. This API cannot be called at the top level of the script.
The product ID for detecting changes in status of owned purchasable items.
Unregisters a purchasable item in ClusterScript.onPurchaseUpdated for detecting changes in status of owned purchasable items. This API cannot be called at the top level of the script.
The product ID for detecting changes in status of owned purchasable items.
Beta
Returns an ItemHandle object that references the Item specified by worldItemReferenceId
in the item's WorldItemReferenceList.
For details on WorldItmeReferenceList
, see documentation.
Supported when called at the top level of the script or from callbacks.
// Item that sends message "click" to the specified item when interacted
const target = $.worldItemReference("target");
$.onInteract(() => {
target.send("click", null);
});
Generated using TypeDoc
The handle to manipulate the item itself. This exists for each individual item, and can be accessed from the
$
object.