Item Readonly idThe string representation of the ID that uniquely identifies a player within the space.
PlayerHandles sharing an identical id will all refer to the same player.
Readonly idfcGet the value of IDFC.
The IDFC is a string that creators can use to uniquely identify a user.
This string is 32 characters long, using the characters 0123456789abcdef.
This string is determined by the pair of the account that uploaded the item/world and the user's account.
It does not change depending on the device or space used by the user.
If the player does not exist, null is returned. The existence of a player can be checked with exists.
This string can be used to improve the content experience. We may restrict its use without notice if we deem it inappropriate.
Readonly typeReturns string "player". This value can be used to distinguish ItemHandle and PlayerHandle.
Readonly userThis is the player's Display Name.
Users can change their own display name, and different users can use the same display name.
If the player does not exist, null is returned. The existence of a player can be checked with exists.
Readonly userBeta
Adds a velocity to the player. The actual movement speed of the player is determined from both the added velocity and player input. While the player is in contact with the ground, the added velocity will gradually decrease, similar to the effects of friction.
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.
Velocity to add (global coordinates)
Obtains the role of the player in the event.
If the space where the player exists is not an event, it returns null.
null may be returned immediately after a player enters the space.
If the player does not exist, null is returned. The existence of a player can be checked with exists.
Player Event Role
Beta
Obtains the position of a player's HumanoidBone.
Values are in global coordinates.
If the avatar has not finished loading yet, or the specified bone does not exist on the avatar, returns null.
Humanoid bone
Beta
Obtains the rotation of a player's HumanoidBone.
Values are in global coordinates.
If the avatar has not finished loading yet, or the specified bone does not exist on the avatar, returns null.
Humanoid bone
Obtains the current rotation of the player in global coordinates. If failed, returns null.
Requests the player to purchase an purchasable item.
The player who is requested to purchase the item will see a purchase dialog for the item. The result of the purchase request is received through the callback of ClusterScript.onRequestPurchaseStatus .
If the player purchases the item, the callback of ClusterScript.onPurchaseUpdated will be called.
If the player closes the dialog without purchasing the item, the purchase is canceled.
If the player cannot display the purchase dialog, the request will be ignored. For example, this includes situations where the item purchase dialog is already being displayed.
If executed during an event, the item cannot be purchased. When using ClusterScript.onRequestPurchaseStatus , the callback will receive PurchaseRequestStatus.NotAvailable.
A single item can act on other ItemHandle and PlayerHandle up to 10 times per second.
It is possible to momentarily exceed this limit, but please ensure the average number of calls does not surpass it.
If the limit is exceeded, a ClusterScriptError (rateLimitExceeded) occurs, 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.
const productId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
$.onStart(() => {
// Save the player's status of owned purchasable items to the state.
$.state.amounts = {};
// Subscribe to purchase notifications.
$.subscribePurchase(productId);
});
$.onUpdate(deltaTime => {
// Check the purchase status of all players regularly, every 10 seconds.
let timer = $.state.timer ?? 0;
timer -= deltaTime;
if (timer <= 0) {
timer += 10;
const allPlayers = $.getPlayersNear(new Vector3(), Infinity);
$.getOwnProducts(productId, allPlayers, "onUpdate");
}
$.state.timer = timer;
});
$.onPurchaseUpdated((player, productId) => {
// If the item is purchased, immediately check the player's purchase status.
$.getOwnProducts(productId, player, "onPurchaseUpdated");
});
$.onGetOwnProducts((ownProducts, meta, errorReason) => {
// Write the status of owned purchasable items to the state.
let amounts = $.state.amounts;
for (let ownProduct of ownProducts) {
let playerId = ownProduct.player.id;
let oldAmount = amounts[playerId] ?? 0;
let newAmount = ownProduct.plusAmount - ownProduct.minusAmount;
amounts[playerId] = newAmount;
}
$.state.amounts = amounts;
});
The product ID for which a purchase is requested.
A string less than 100 bytes. It can be used to identify multiple requestPurchase calls. It is fine to specify an empty string or the same string multiple times.
Requests the player to input a text string.
The text string from the player can be received in a callback set in ClusterScript.onTextInput. If the player is unable to respond to the input request, the request is automatically refused. An example of this is a situation where the player received a new input request, but was already in the middle of an earlier input request. The player can also intentionally refuse input requests. The outcome of the input request is represented in TextInputStatus.
$.onInteract(player => {
player.requestTextInput("ask_name", "Hi, what is your name?");
});
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.
A text string in 100 bytes or less. Useful for distinguishing between multiple requestTextInput calls. Empty or reused strings are allowed.
A text string to display to the player who received the input request. Must be 200 bytes or less.
Resets any movement velocity, jumping speed, and gravity applied to the player. The movement speed, jump speed, and gravity specified by PlayerScript will also be reset.
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.
Respawns the player.
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.
Send a message to PlayerScript.
The sent target is expected to call the callback set in PlayerScript.onReceive.
For data types that can be used as the message's payload (the arg argument), refer to Sendable.
The following is an example of sending an message.
playerHandle.send("damage", 20);
In the following example, the item handle is sent to the player who Interacted to the item.
$.onInteract(player => {
player.send("item-handle", $.itemHandle);
});
How to handle the received message is described in PlayerScript.onReceive of the receiving PlayerScript. In the following example, store the received ItemId in a variable. For this ItemId, you can perform processing such as PlayerScript.sendTo of a message when necessary.
let itemId = null;
_.onReceive((messageType, arg, sender) => {
switch (messageType) {
case "item-handle":
itemId = arg;
break;
}
});
Sendable sent for PlayerScript will be converted to PlayerScriptSendable. Specifically, ItemHandle is converted to ItemId and PlayerHandle is converted to PlayerId.
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.
The data size of the encoded arg must be less than 1000 bytes.
If the data size exceeds the limit, a warning will be displayed.
Data size can be calculated with computeSendableSize.
If the data size is much larger than the limit, ClusterScriptError (requestSizeLimitExceeded) will occur and send will fail.
Arbitrary string of 100 bytes or less indicating the message type
Message Payload
Modifies the gravitational acceleration applied to the player. (Units are in m/s^2.) The default is -9.81.
The setting is shared with PlayerHandle.setGravity. The value of the one called later will overwrite it.
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.
Gravitational acceleration value
Overwrites the pose of the player's avatar model with the specified HumanoidPose.
The pose data override method can be specified with option; see SetHumanoidPoseOption for properties that can be specified by option.
The argument option can be omitted. If it is omitted, the default setting is used.
If the rootPosition, rootRotation, or muscle of the given HumanoidPose are not defined, they will not be overwritten.
Additionally, option.timeoutSeconds and option.timeoutTransitionSeconds won't affect behavior for unspecified elements and will not be overwritten.
Pose overwrites will persist until the next time setHumanoidPose is called or the pose data is cancelled at the timeout specified by option.
To remove all previous overwrites made with setHumanoidPose, pass a null or an empty HumanoidPose as the argument.
If a null or empty HumanoidPose is passed with HumanoidPoseOption, it will transition to the remove all previous overwrites after HumanoidPoseOption.transitionSeconds.
Pose overwrites made through setHumanoidPose will take precedence over pose changes made from emotes or RidableItems.
In VR, items being grabbed by the player will follow the specified pose, but elements such as the first-person camera, UI controls, etc. will be unaffected.
// Register a HumanoidAnimation with the ID "MyAnimation"
const animation = $.humanoidAnimation("MyAnimation");
// Overwrite the pose
playerHandle.setHumanoidPose(animation.getSample(0));
// Remove the overwrite
playerHandle.setHumanoidPose(null);
const animation = $.humanoidAnimation("MyAnimation");
const interval = 0.1;
const animationLength = animation.getLength();
// Make the person you Interact with the target of the animation.
$.onInteract(player => {
if ($.state.player) {
// Deactivate when the target is already present.
$.state.player.setHumanoidPose(null);
}
$.state.animationTime = 0;
$.state.waitingTime = 0;
$.state.player = player;
});
$.onUpdate(deltaTime => {
let player = $.state.player;
if (!player || !player.exists()) return;
let animationTime = $.state.animationTime + deltaTime;
if (animationTime > animationLength) {
animationTime = animationTime % animationLength;
}
let waitingTime = $.state.waitingTime + deltaTime;
if (waitingTime >= interval) {
let pose = animation.getSample(animationTime);
// Transition the pose data over the amount of time since the last transmission.
player.setHumanoidPose(pose, {transitionSeconds: waitingTime});
waitingTime = 0;
}
$.state.animationTime = animationTime;
$.state.waitingTime = waitingTime;
});
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.
Modifies the player's jumping speed multiplier. The default is 1.
The setting is shared with PlayerScript.setJumpSpeedRate. The value of the one called later will overwrite it.
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.
Jumping speed multiplier
Modifies the player's movement speed multiplier. The default is 1.
The setting is shared with PlayerScript.setMoveSpeedRate. The value of the one called later will overwrite it.
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.
Movement speed multiplier
Modifies the position of the player.
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.
The avatar's root position, corresponding to the bottom center of the avatar's feet. (global coordinates)
Beta
Sets post-process effects for the player.
Each time this method is called, the previously set PostProcessEffects are overwritten with the new PostProcessEffects.
Setting null clears all effects.
The settings are shared with PlayerScript.setPostProcessEffects. The value of the one called later will overwrite it.
A single item can act on other ItemHandle and PlayerHandle up to 10 times per second.
It is possible to momentarily exceed this limit, but please ensure the average number of calls does not surpass it.
If the limit is exceeded, a ClusterScriptError (rateLimitExceeded) occurs, 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.
// The screen becomes very bright when interacted with
$.onInteract((player) => {
const effects = new PostProcessEffects();
effects.bloom.active = true;
effects.bloom.threshold.setValue(0.5);
effects.bloom.intensity.setValue(10.0);
player.setPostProcessEffects(effects);
});
An instance of PostProcessEffects.
Modifies the rotation of the player. Note the body orientation will stay vertical. (the camera and neck directions will be affected by the pitch.)
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.
The player's rotation (global coordinates)
Generated using TypeDoc
A handle to externally manipulate the player. The
PlayerHandlestays the same even if the player changes their avatar. A user is treated as a different player every time they enter a room. Therefore, a newPlayerHandlewill need to be acquired again for users who left and joined back in.In events, ghosts and group viewing users cannot be retrieved from script. For details, refer to the documentation.