Meta Developers

API reference

Player Class

Represents a player in the world. This is the primary class for managing an individual player's physical presence and game play in the world, including their avatar.

Signature

export declare class Player

Constructors

(constructor)(id)

Creates a player in the world.

Signature

constructor(id: number);

Parameters

id: number

The ID of the player.

Properties

avatarScale	The scale of the player's avatar. Change this to scale the player up or down. Signature avatarScale: HorizonProperty<number>; Examples This example demonstrates how to modify the avatar scale of a player when it enters a trigger. class AvatarScalingExample extends hz.Component<typeof AvatarScalingExample> { static propsDefinition = { newAvatarScale: { type: hz.PropTypes.Number }, }; start() { this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerEnterTrigger, (player) => { player.avatarScale.set(this.props.newAvatarScale); }); } } hz.Component.register(AvatarScalingExample); Remarks Accepts values between 0.05 and 50. The scaling happens with a one frame delay.
deviceType	Gets the type of device the player is using. Signature deviceType: ReadableHorizonProperty<PlayerDeviceType>; Remarks New device types may be added in the future, so you should handle this property with a switch statement.
focusedInteraction	The FocusedInteraction instance associated with the player. Signature focusedInteraction: FocusedInteraction; Remarks Focused Interaction mode replaces on-screen controls on web and mobile clients with touch and mouse input that includes direct input access. For more information about Focused Interaction, see the Focused Interaction guide.
foot	The player's foot. Signature foot: PlayerBodyPart;
forward	The player's forward direction relative to the world origin. Signature forward: ReadableHorizonProperty<Vec3>;
gravity	The player's gravity before simulation. Signature gravity: HorizonProperty<number>;
head	The player's head. Signature head: PlayerBodyPart;
id [readonly]	The player's ID. Signature readonly id: number;
index	The index that identifies the player in the list of all players in the world instance. Signature index: ReadableHorizonProperty<number>; Examples This example demonstrates how to retrieve a `Player` object using a player index. var playerIndex = player.index.get(); var playerFromIndex = this.world.getPlayerFromIndex(playerIndex); Remarks When joing a world, each player is assigned an index, which ranges from 0 (the first player) to `Max Players - 1`. Use the index value to keep track of players and get a `Player` object using the World.getPlayerFromIndex() method.
isGrounded	Indicates whether the player is grounded (touching a floor). If a player is grounded then gravity has no effect on their velocity. Signature isGrounded: ReadableHorizonProperty<boolean>;
isInBuildMode	Indicates whether a player is in build mode. Signature isInBuildMode: ReadableHorizonProperty<boolean>; Remarks Build mode means the player is editing the world. The alternative, preview mode, is when they're playing the world.
jumpSpeed	The speed applied to a player when they jump, in meters per second. Setting this to 0 effectively disables a player's ability to jump. Signature jumpSpeed: HorizonProperty<number>; Remarks Default value is 4.3. jumpSpeed must be a value between 0 and 45. `jumpSpeed.set` can be called on any player from any context, but `jumpSpeed.get` will throw an error unless it's called from a local script attached to an object owned by the player in question.
leftHand	The player's left hand. Signature leftHand: PlayerHand;
locomotionSpeed	The speed at which the player moves, in meters per second. Signature locomotionSpeed: HorizonProperty<number>; Remarks Default value is 4.5. locomotionSpeed must be a value between 0 and 45. `locomotionSpeed.set` can be called on any player from any context, but `locomotionSpeed.get` will throw an error unless it's called from a local script attached to an object owned by the player in question.
name	The player's name displayed in the game. Signature name: ReadableHorizonProperty<string>;
position	The player's position relative to the world origin. Signature position: HorizonProperty<Vec3>;
rightHand	The player's right hand. Signature rightHand: PlayerHand;
rootRotation	The root rotation of the player's avatar. This is different from the Player.rotation property, which retrieves the player's head rotation. Signature rootRotation: HorizonProperty<Quaternion>; Examples class ServerRotate extends hz.Component<typeof ServerRotate> { static propsDefinition = { lookAtProp : { type: hz.PropTypes.Entity }, }; start() { this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerEnterWorld, (player: hz.Player) => { serverPlayer = player; console.log("Starting interval Server"); this.async.setInterval(() => { if(serverPlayer != undefined) { var rootRotation = serverPlayer.rootRotation.get(); console.log("Server: " + rootRotation.toString()); } }, 5000); }); this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerEnterTrigger, (player: hz.Player) => { if(this.props.lookAtProp) { var lookVector = this.props.lookAtProp.position.get().sub(player.position.get()); var newRotation = hz.Quaternion.lookRotation(lookVector.normalize()); player.rootRotation.set(newRotation); } }); } } Remarks When setting, only the yaw component of the input rotation is used, keeping the character upright.
rotation	The player's facing/head rotation relative to the world origin. For the rotation of the player's entire avatar, see the Player.rootRotation property. Signature rotation: ReadableHorizonProperty<Quaternion>; Examples var headRotation = serverPlayer.rotation.get();
torso	The player's torso. Signature torso: PlayerBodyPart;
up	The player's up direction relative to the world origin. Signature up: ReadableHorizonProperty<Vec3>;
velocity	The player's velocity relative to the origin, in meters per second, due to physics and not locomotion input. Signature velocity: HorizonProperty<Vec3>;

Methods

applyForce(force)	Applies a force vector to the player. Signature applyForce(force: Vec3): void; Parameters force: Vec3 The force vector applied to the player's body. Returns void
clearAimAssistTarget()	Disables Aim Assistance for a player by clearing the current target. This method must be called on a local player and doesn't affect VR players. Signature clearAimAssistTarget(): void; Returns void Remarks For information about using Aim Assist, see the Aim Assist guide for web and mobile.
clearAvatarGripPoseOverride()	Clears any override on an avatar grip pose, reverting it to the pose of the currently held grabbable. Signature clearAvatarGripPoseOverride(): void; Returns void Remarks For information on overriding an avatar grip pose, see .
configurePhysicalHands(collideWithDynamicObjects, collideWithStaticObjects)	Specifies whether physical hands can collide with objects. Signature configurePhysicalHands(collideWithDynamicObjects: boolean, collideWithStaticObjects: boolean): void; Parameters collideWithDynamicObjects: boolean Indicates whether physical hands can collide with dynamic objects. collideWithStaticObjects: boolean Indicates whether physical hands can collide with static objects. Returns void
enterFocusedInteractionMode()	Enables Focused Interaction mode for the player. Signature enterFocusedInteractionMode(): void; Returns void Remarks This method must be called on a local player and has no effect on VR players. Focused Interaction mode replaces on-screen controls on web and mobile clients with touch and mouse input that includes direct input access. Player.exitFocusedInteractionMode() disables Focused Interaction mode. When Focused Interaction mode is enabled, you can recieve input data from the PlayerControls.onFocusedInteractionInputStarted, PlayerControls.onFocusedInteractionInputMoved, and PlayerControls.onFocusedInteractionInputEnded events. For more information, see the Focused Interaction guide.
exitFocusedInteractionMode()	Disables Focused Interaction mode for the player. Signature exitFocusedInteractionMode(): void; Returns void Remarks This method must be called on a local player and has no effect on VR players. Player.enterFocusedInteractionMode() enables Focused Interaction mode. When Focused Interaction mode is enabled, you can recieve input data from the PlayerControls.onFocusedInteractionInputStarted, PlayerControls.onFocusedInteractionInputMoved, and PlayerControls.onFocusedInteractionInputEnded events. For more information, see the Focused Interaction guide.
focusUI(selectable, options)	Focuses the player's camera on the given selectable entity in the world, such as a custom UI. This method only affects web and mobile clients. Signature focusUI(selectable: Entity, options?: FocusUIOptions): void; Parameters selectable: Entity The selectable entity to focus on. options: FocusUIOptions (Optional) The options to apply to, such as settings for the camera view and animation transitions. Returns void Remarks You can use this method along with the method to manage the camera focus when creating a custom UI component. For more information about creating custom UI components, see the Custom UI panel guide.
hasCompletedAchievement(achievementScriptID)	Indicates whether a player has completed an achievement. Signature hasCompletedAchievement(achievementScriptID: string): boolean; Parameters achievementScriptID: string The scriptID of the achievement. This can be accessed and set on the Achievements page in the VR creator UI. Returns boolean `true` if the player has the achievement, `false` otherwise. Examples var WonAGameAchievementScriptID = "wonAGame" var hasAchievement = player.hasCompletedAchievement(WonAGameAchievementScriptID)
playAvatarAnimation(animation, options)	Plays an animation asset on the player's avatar one time. Signature playAvatarAnimation(animation: Asset, options?: PlayAnimationOptions): void; Parameters animation: Asset options: PlayAnimationOptions (Optional) The options that control how to play the animation. Returns void Remarks This method allows you to use custom animations for player avatars and access callbacks that allow your scripts to respond when the animation starts and stops.
playAvatarGripPoseAnimationByName(avatarGripPoseAnimationName, options)	Triggers an AvatarGripPose animation by name, one time. Signature playAvatarGripPoseAnimationByName(avatarGripPoseAnimationName: string, options?: PlayAvatarGripPoseAnimationOptions): void; Parameters avatarGripPoseAnimationName: string The avatar grip pose animation to play. options: PlayAvatarGripPoseAnimationOptions (Optional) The optional parameters that influence how the animation is handled. Returns void Examples player.playAvatarGripPoseAnimationByName(AvatarGripPoseAnimationNames.Fire, {callback: (reason: hz.AnimationCallbackReasons) => {}}); Remarks For more information about using this method, see the Player Animations guide.
setAchievementComplete(achievementScriptID, complete)	Specifies whether the player's achievement is complete. Signature setAchievementComplete(achievementScriptID: string, complete: boolean): void; Parameters achievementScriptID: string The scriptID of the achievement. This can be accessed/set on the Achievements page in the VR creator UI. complete: boolean `true` sets the achievement to complete; `false` sets the achievement to incomplete. Returns void Examples var WonAGameAchievementScriptID = "wonAGame" player.setAchievementComplete(WonAGameAchievementScriptID, true)
setAimAssistTarget(target, options)	Enables Aim Assistance on a target. This generates a force pulling the cursor towards a target when the aim cursor approaches it. Signature setAimAssistTarget(target: Player \| Entity \| Vec3, options?: AimAssistOptions): void; Parameters target: Player \| Entity \| Vec3 The target that receives Aim Assistance. options: AimAssistOptions (Optional) The options to use when applying Aim Assistance. Returns void Remarks This method must be called on a local player and has no effect on VR players.
setAvatarGripPoseOverride(avatarGripPose)	Overrides the existing HWXS avatar grip type, which is determined by the currently held grabbable. Signature setAvatarGripPoseOverride(avatarGripPose: AvatarGripPose): void; Parameters avatarGripPose: AvatarGripPose The new pose to apply. This persists until cleared or another grip override is set. For information on clearing an override, see . Returns void
setVoipSetting(setting)	Sets the VOIP setting for the player. Signature setVoipSetting(setting: VoipSetting): void; Parameters setting: VoipSetting The VOIP setting to use. Returns void
stopAvatarAnimation(options)	Stops any avatar animation asset that is playing. Signature stopAvatarAnimation(options?: StopAnimationOptions): void; Parameters options: StopAnimationOptions (Optional) The options that control the animation. Returns void Remarks The Player.stopAvatarAnimation() method is used to play custom avatar animations.
throwHeldItem(options)	Attempts throws the item held in the specified hand. Signature throwHeldItem(options?: Partial<ThrowOptions>): void; Parameters options: Partial<ThrowOptions> (Optional) Options to adjust the throwing speed, yaw, pitch, and animation. Returns void
toString()	Creates a human-readable representation of the player. Signature toString(): string; Returns string A string representation of the player.
unfocusUI()	Removes focus from any in-world UI the player's camera is currently focused on. This method only affects web and mobile clients. Signature unfocusUI(): void; Returns void Remarks You can use this method along with the Player.focusUI() method to manage the camera focus when creating a custom UI component. For more information about creating custom UI components, see the Custom UI panel guide.