Interface PlayerScriptPlayer

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.

Calculate the data size when sending data from PlayerScript and return the number of bytes. If the data is not supported by send, TypeError will be generated.

Gets the avatar's movement and motion status as a list of bitmasked flags. The defined bitflags are as follows:

• 0x0001: On if the avatar is on the ground, off if in the air due to jumping or falling
• 0x0002: On if the avatar is climbing, off otherwise
• 0x0004: On if the avatar is riding on items, off otherwise

Flags may be added in future updates, so use a value with the bitflag masked.

Example

// Example of a function to get bit flags and output logs
function getStatus() {
  let flags = _.getAvatarMovementFlags();
  let isGrounded = (flags & 0x0001) !== 0;
  let isClimbing = (flags & 0x0002) !== 0;
  let isRiding = (flags & 0x0004) !== 0;
  _.log(`isGrounded: ${isGrounded}, isClimbing: ${isClimbing}, isRiding: ${isRiding}`);
}

Returns

Flags about avatar movement status

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.

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.

Get the value of IDFC of the player. 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 combination of the account that uploaded the item that is the source of the PlayerScript and the user's account. The source item is the item that called $.setPlayerScript() and can be obtained with _.sourceItemId. It does not change depending on the device or space used by the user. It returns null for players who have left the room or for invalid PlayerId.

This string can be used to improve the content experience. We may restrict its use without notice if we deem it inappropriate.

Gets data in the player's PlayerStorage.

This API is not available from Craft Items.

For details on PlayerStorage, see setPlayerStorageData.

Example

// Example code to get the saved level when a player starts the game
let level;
const storageData = _.getPlayerStorageData();
if (storageData === null) {
  level = 1;
} else {
  level = storageData.level;
}

Returns

The data currently saved in PlayerStorage

Obtains the current position of the player in global coordinates.

Returns null if the value cannot be obtained.

You can also get player's movement status with PlayerScript.getAvatarMovementFlags.

Returns

The player's position

Obtains the current rotation of the player in global coordinates.

Returns null if the value cannot be obtained.

You can also get player's movement status with PlayerScript.getAvatarMovementFlags.

Returns

The player's rotation

Get the player's display name. Users can change their display names, and different users can use the same display name. It returns null for players who have left the room or for invalid PlayerId.

Get the player's User ID. Users can change their own User ID, but no two different users can have the same User ID at the same time. null is returned for players who have left the room or for invalid PlayerId.

Hides the button shown by PlayerScript.showButton. Does nothing if the specified button is already hidden.

In desktop and mobile environments, when called with index = 0, the behavior of the "Use" button will revert to normal, and the button availability will be controlled by UseItemTrigger and ClusterScript.onUse callback.

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.

Gets the icon object corresponding to the specified iconId defined by Icon Asset List component. See details of the component at Icon Asset List. You can use the data with PlayerScript.showButton to show the buttons with specified icon.

Output the toString contents of v to the log.

Registers the callback method for the button shown by PlayerScript.showButton. The callback will be called with isDown = true when pressed, and called again with isDown = false when the button is released. The method is available before showing the button, and the registration state is maintained even if the button is hidden.

If called multiple times, only the last registration will be valid per button index.

This callback is not necessarily called with isDown = false after being called with isDown = true. For example, if you press a button and then call hideButton to hide the button, the callback with isDown = false will not be called.

Register a callback that will be called every frame. This callback is guaranteed to be called every frame.

If called multiple times, only the last registration is valid.

Example

// Output logs at 10 second intervals.
let t = 0;
_.onFrame(deltaTime => {
    t += deltaTime;
    if (t > 10) {
        _.log("10 sec elapsed.");
        t -= 10;
    }
});

Registers a callback to be called when this item receives a message sent from PlayerHandle.send or sent from PlayerScript.sendTo to PlayerId.

If called multiple times, only the last registration will be valid.

You can specify the type of message to receive with option.

If option is not set, it will receive both messages from PlayerHandle.send and messages sent to PlayerId by PlayerScript.sendTo. PlayerScript.sendTo | PlayerScript.sendTo}.

• If option.item is true, then messages sent from PlayerHandle.send will be received.
• If option.item is false, then messages sent from PlayerHandle.send will be ignored.
• If option.item is unset, then messages sent from PlayerHandle.send will be received.
• If option.player is true, then messages sent from PlayerScript.sendTo will be received.
• If option.player is false, then messages sent from PlayerScript.sendTo will be ignored.
• If option.player is unset, then messages sent from PlayerScript.sendTo will be received.

Example

// Output log of messages sent.
_.onReceive((messageType, arg, sender) => {
  _.log(`Received message: ${messageType}, ${arg}`);
});

Example

// Outputs a log of messages sent. Receive only messages from items.
_.onReceive((messageType, arg, sender) => {
  _.log(`Received message: ${messageType}, ${arg}`);
}, { player: false, item: true });

Gets the object specified by id in Player Local Object Reference List. See detail at Player Local Object Reference List. Returns null if id is not defined in the component or the object does not match the condition defined in the component page.

Casts a ray, and returns the first object it collided with.

Example

// Casts a ray toward Z axis positive direction in item local coordinates, and logs the nearest object hit.
let direction = new Vector3(0, 0, 1).applyQuaternion($.getRotation());
let result = $.raycast($.getPosition(), direction, 10);
if (result === null) {
  $.log("ray hits nothing");
} else if (result.handle === null) {
  $.log("ray hits something other than player or item");
} else if (result.handle.type === "player") {
  $.log("ray hits player " + result.handle.userDisplayName);
} else if (result.handle.type === "item") {
  $.log("ray hits item " + result.handle.id);
}

Returns

The collided object (null if no collision)

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.

Example

// Casts a ray downwards, and move the item itself to the nearest hit position which target is not item or player.
let raycastResults = $.raycastAll($.getPosition(), new Vector3(0, -1, 0), 10);
let result = null;
let minDistance = Infinity;
for (let raycastResult of raycastResults) {
  if (raycastResult.handle !== null) continue;
  var distance = raycastResult.hit.point.clone().sub(pos).length();
  if (distance >= minDistance) continue;
  result = raycastResult;
  minDistance = distance;
}
if (result != null) {
  $.setPosition(result.hit.point);
}

Returns

An array of the collided objects (order is undefined)

Resets any movement velocity, jumping speed, and gravity applied to the player. The movement speed, jump speed, and gravity specified by PlayerHandle will also be reset.

Respawns the player.

Send a message to the item/player. The sent target is expected to call a callback set using ClusterScript.onReceive or PlayerScript.onReceive. See PlayerScriptSendable for data that can be used in the message payload (the arg argument).

Ignored for deleted items and for invalid ItemId. Ignored for players who have left the room and for invalid PlayerId.

If sent for an ItemId, PlayerScriptSendable will be converted to Sendable.

There is a limit on how often sendTo can be called.

• When called from a craft item, it must not exceed 10 calls per second per item
• When called from a world item, the total number of calls to send, send, and sendTo from all world items in the space must not exceed 3000 calls per second

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 sendTo 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 sendTo will fail.

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.

Sets the specified bone's rotation. Values are in global coordinates. The rotation specified by this method is applied only to that frame and does not affect the next frame or later.

This method does nothing when the specified bone does not exist in the avatar.

The bone rotations specified by this function take precedence over the pose specified by PlayerHandle.setHumanoidPose. In VR, items held by the player will follow the specified pose, but the first-person camera and UI operations are not affected.

Overwrites the pose of the player's avatar model with the specified HumanoidPose. The pose specified by this method is applied only to that frame and does not affect the next frame or later.

If the rootPosition, rootRotation, or muscle of the given HumanoidPose are not defined, they will not be overwritten.

weight represents the application rate of the specified pose as a number between 0 and 1. Calling the method with weight = 1 applies the pose completely. weight is optional, and treated as 1 is specified if omitted.

The pose specified by this function takes precedence over PlayerHandle.setHumanoidPose. In VR, items held by the player will follow the specified pose, but the first-person camera and UI operations are not affected.

Modifies the player's jumping speed multiplier. The default is 1.

The setting is shared with PlayerHandle.setJumpSpeedRate. The value of the one called later will overwrite it.

Modifies the player's movement speed multiplier. The default is 1.

The setting is shared with PlayerHandle.setMoveSpeedRate. The value of the one called later will overwrite it.

Overwrites data in the player's PlayerStorage.

See PlayerScriptSendable for data that can be saved (the data argument).

This API is not available from Craft Items.

PlayerStorage is an area for saving data that exists per player in each world or event. If setPlayerStorageData has never been called, null is stored in the PlayerStorage.

In worlds, the data in PlayerStorage is saved even if the player leaves the world. When the player returns to the world, they can get the saved data. PlayerStorage can also store PlayerId and ItemId, but these do not necessarily represent players or items that are valid in other spaces.

In events, each time a player enters, PlayerStorage is initialized, and null is set. Even if the data in PlayerStorage is overwritten during an event, the data in PlayerStorage of the original Event Venue remains unchanged.

The data in PlayerStorage can be deleted from the World Manager. See here for details.

The data size of the encoded data must be less than or equal to 10,000 bytes. The data size can be calculated using computeSendableSize.

If the data size is larger than the limit, ClusterScriptError (requestSizeLimitExceeded) will occur and setPlayerStorageData will fail.

Example

// Example code that levels up when receiving a levelUp message and saves the result.
let level = 1;
_.onReceive((messageType, arg, sender) => {
  if (messageType === "levelUp") {
    level += 1;
    _.setPlayerStorageData({ level });
  }
});

Sets the position of the player in global coordinate.

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 PlayerHandle.setPostProcessEffects. The value of the one called later will overwrite it.

Example

// A button that becomes very bright when pressed.
_.onButton(0, (isDown) => {
    if (!isDown) return;
    const effects = new PostProcessEffects();
    effects.bloom.active = true;
    effects.bloom.threshold.setValue(0.5);
    effects.bloom.intensity.setValue(10.0);
    _.setPostProcessEffects(effects);
});

Sets the rotation of the player in global coordinate.

Note the body orientation will stay vertical.

Displays a button UI corresponding to the specified integer value, or starts monitoring key/mouse click inputs that are treated as equivalent to a button. If called on a button that is already displayed, the icon will be updated. Up to four button inputs can be presented in this way.

To display buttons with this function, the Use Cluster HUD v2 option must be enabled on the world's WorldRuntimeSetting component. Use PlayerScript.onButton to register the callback for the buttons.

In desktop and mobile environments, the button corresponding to index = 0 is the same as the "Use" button of the item with UseItemTrigger component. Other buttons are only displayed by calling this function. If this function is called with index = 0, the display content of the button set by this function and the callback registered with PlayerScript.onButton will take priority over the "Use" button of the item until PlayerScript.hideButton is called with index = 0. Pressing a button will not fire UseItemTrigger and ClusterScript.onUse callback.

Buttons displayed by this function will be hidden when PlayerScript.hideButton is called or when the validity period of the Player Script expires.

In a mobile environment, buttons are placed in specific positions according to their numbers. In a desktop environment, the following key assignments are applied to buttons 0, 1, 2, and 3.

• 0: Left click
• 1: Right click
• 2: E key
• 3: R key

In a VR environment, when one or more buttons are enabled, pulling the trigger on the right-hand controller will display a pie menu. Tilting the stick then inputs the corresponding button. On the pie menu, the buttons correspond to 0, 1, 2, and 3, arranged counterclockwise starting from the right.

In a desktop environment, cursor operation on the screen is locked while one or more buttons are displayed, and clicks and key inputs during cursor lock are treated as button inputs. If buttons are displayed and hidden very frequently, this automatic cursor lock will be disabled for a certain period of time.

Returns an ItemId object that references the Item specified by worldItemReferenceId in the item's WorldItemReferenceList.

For details on WorldItmeReferenceList, see documentation.

Example

// Item that sends message "button" to the specified item when button 0 is pressed
const target = _.worldItemReference("target");

_.onButton(0, isDown => {
  if (isDown) _.sendTo(target, "button", null);
});