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.

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

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

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.

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

Deprecated

_.onStart() is deprecated. If you want to perform a one-time process when PlayerScript is initialized, write it directly at the top level of the script instead.

Example

// Don't
_.onStart(() => {
  _.log("PlayerScript is initialized.");
});

// Do
_.log("PlayerScript is initialized.");

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)

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.

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

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