Interface PlayerScriptPlayer Beta

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.

Obtains the current position of the player in global coordinates.

Returns null if avatar loading is not completed.

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 avatar loading is not completed.

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

Returns

The player's rotation

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

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.

In VR environment, this method has no effect since PlayerScript.showButton does nothing in that case. You can check whether the player is in a VR environment with PlayerScript.isVr.

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.

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.

Only calls at the top level of the script are supported. If called multiple times at the top level, 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.

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.

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 });

Register a callback that will be called once when this PlayerScript is initialized, before onFrame is executed for the first time.

When this PlayerScript is initialized means when the script in the Player Script component attached to the item is registered in the PlayerScript by using $.setPlayerScript(), and then the script is activated.

Only top-level calls to the script are supported. If called multiple times at the top level, only the last registration will be activated.

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

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.

Returns

An array of the collided objects (order is undefined)

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.

One PlayerScript can be sent messages up to 10 times/second. You can exceed this limit momentarily, but the average number of times should be below this limit. If the limit is exceeded, ClusterScriptError (rateLimitExceeded) occurs and sendTo will 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.

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.

Sets the position of the player in global coordinate.

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.

This function only works on desktop and mobile, and calling it in a VR environment will have no effect. Buttons presented in this way are particularly useful for improving the expressiveness of non-VR users, such as executing motions. You can check whether the player is in a VR environment with PlayerScript.isVr.

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 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.

Supported when called at the top level of the script or from callbacks.

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);
});