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 idfcA 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 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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
Velocity to add (global coordinates)
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
Humanoid bone
Obtains the current position of the player in global coordinates. If failed, returns null.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
Obtains the current rotation of the player in global coordinates. If failed, returns null.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
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.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
Modifies the gravitational acceleration applied to the player. (Units are in m/s^2.) The default is -9.81.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
Gravitational acceleration value
Beta
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
Modifies the player's jumping speed multiplier. The default is 1.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
Jumping speed multiplier
Modifies the player's movement speed multiplier. The default is 1.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
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.
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.
This method can only be executed on players within 30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) occurs, and the operation will fail.
// 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.
This method can only be used to target players within
30 meters of the item executing this script.
If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and the operation will fail.
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.