Player
Beta
Readonly
Beta
cameraGets the handle to control camera movement.
Readonly
Beta
isGets whether the player is in an Android environment.
Returns true if in a Quest environment.
Readonly
Beta
isGets whether the player is in a desktop environment.
Returns false if in a VR or mobile environment.
Readonly
Beta
isGets whether the player is in an iOS environment.
Readonly
Beta
isGets whether the player is in a macOS environment.
Readonly
Beta
isGets whether the player is in a mobile environment.
Returns false if in a VR or desktop environment.
Readonly
Beta
isGets whether the player is using VR devices.
Readonly
Beta
isGets whether the player is in a Windows environment.
Readonly
Beta
sourceItemId of the source Item that has the Player Script component that called ClusterScript.setPlayerScript.
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.
Beta
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 falling0x0002
: On if the avatar is climbing, off otherwise0x0004
: On if the avatar is riding on items, off otherwiseFlags may be added in future updates, so use a value with the bitflag masked.
// 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}`);
}
Flags about avatar movement status
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
Beta
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.
The player's position
Beta
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.
The player's rotation
Beta
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.
The button number, either 0, 1, 2, or 3. Other value will result an error.
Beta
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.
Beta
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.
Id of the icon asset
Beta
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.
The button number, either 0, 1, 2, or 3. Other value will result an error.
method that is called when the button is pressed or released.
Beta
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.
// Output logs at 10 second intervals.
let t = 0;
_.onFrame(deltaTime => {
t += deltaTime;
if (t > 10) {
$.log("10 sec elapsed.");
t -= 10;
}
});
Beta
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}.
option.item
is true
, then messages sent from PlayerHandle.send will be received.option.item
is false
, then messages sent from PlayerHandle.send will be ignored.option.item
is unset, then messages sent from PlayerHandle.send will be received.option.player
is true
, then messages sent from PlayerScript.sendTo will be received.option.player
is false
, then messages sent from PlayerScript.sendTo will be ignored.option.player
is unset, then messages sent from PlayerScript.sendTo will be received.// Output log of messages sent.
_.onReceive((messageType, arg, sender) => {
$.log(`Received message: ${messageType}, ${arg}`);
});
// Outputs a log of messages sent. Receive only messages from items.
_.onReceive((messageType, arg, sender) => {
$.log(`Received message: ${messageType}, ${arg}`);
}, { player: false, item: true });
sender represents the item or player from which it is sent.
Optional
option: { item: boolean; player: boolean }Option to register callbacks. You can specify the type of message to receive。
Beta
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.
Beta
Casts a ray, and returns the first object it collided with.
The collided object (null
if no collision)
Beta
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.
An array of the collided objects (order is undefined)
Beta
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.
Beta
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.
Bone to rotate
Rotation of the bone
Beta
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.
The pose to apply
The weight to apply the pose
Beta
Sets the rotation of the player in global coordinate.
Note the body orientation will stay vertical.
The player's rotation
Beta
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.
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.
The button number, either 0, 1, 2, or 3. Other value will result an error.
The icon to show on the button. When the icon is invalid, then treated as the icon is not specified.
Beta
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.
// 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);
});
Generated using TypeDoc
A handle to manipulate PlayerScript. It can be accessed from
_
objects.PlayerScript is generated by setting ClusterScript.setPlayerScript.