| source |
|---|
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.
export declare class Player Creates a player in the world.
Signature
constructor(id: number, entity?: Entity);Parameters
id: number
The ID of the player.
entity: Entity
(Optional) An optional NPC Gizmo entity associated with the player.
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.
The multiplier applied to a player's locomotion speed when they are backpedaling.
Signature
backpedalMultiplier: HorizonProperty<number>;Examples
This example demonstrates how to modify the player backpedal multiplier while it is inside a trigger.
import * as hz from 'horizon/core';
class BackpedalMultiplierExample extends hz.Component<typeof BackpedalMultiplierExample> {
static propsDefinition = {
modifiedBackpedalMultiplier: { type: hz.PropTypes.Number },
};
private defaultBackpedalMultiplier: number = 0.825;
start() {
this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerEnterTrigger, (player) => {
var extendedPlayer = new hz.Player(player.id);
extendedPlayer.backpedalMultiplier.set(this.props.modifiedBackpedalMultiplier);
});
this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerExitTrigger, (player) => {
var extendedPlayer = new hz.Player(player.id);
extendedPlayer.backpedalMultiplier.set(this.defaultBackpedalMultiplier);
});
}
}
hz.Component.register(BackpedalMultiplierExample);Remarks
Default value is 0.825. backpedalMultiplier must be a value between 0 and 10. backpedalMultiplier.set can be called on any player from any context, but backpedalMultiplier.get will throw an error unless it's called from a local script attached to an object owned by the player in question.Using the Orbit, Pan, and Follow camera modes will prevent the user from backpedaling.
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.
The player's ID.
Signature
readonly entity?: Entity;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.
The player's foot.
Signature
foot: PlayerBodyPart;The player's forward direction relative to the world origin.
Signature
forward: ReadableHorizonProperty<Vec3>;The player's gravity before simulation.
Signature
gravity: HorizonProperty<number>;The player's head.
Signature
head: PlayerBodyPart;The player's ID.
Signature
readonly id: number;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.
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>;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.
Indicates whether the NPC is performing a jump.
Signature
isJumping: ReadableHorizonProperty<boolean>;Indicates whether the player is moving.
Signature
isMoving: ReadableHorizonProperty<boolean>;Indicates whether the player is moving using scripted navigation.
Signature
isNavigating: ReadableHorizonProperty<boolean>;Whether or not the player is still a valid player reference, and hasn't been disposed. Useful in asynchronous contexts (async/awaits, promise.then's, and networkEvents).
Signature
isValidReference: ReadableHorizonProperty<boolean>;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.
The player's left hand.
Signature
leftHand: PlayerHand;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.
The player's name displayed in the game.
Signature
name: ReadableHorizonProperty<string>;The name tag for the player.
Signature
readonly nameTag: NameTag;The player's position relative to the world origin.
Signature
position: HorizonProperty<Vec3>;The player's right hand.
Signature
rightHand: PlayerHand;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.
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();Gets the screen height of the screen surface the player is using.
Signature
screenHeight: ReadableHorizonProperty<number>;Remarks
The returned value is the size of the renderable screen height in pixels, and is not guaranteed to match the actual player's device screen width.
Gets the safe area of the screen surface the player is using.
Signature
screenSafeArea: ReadableHorizonProperty<Rect>;Remarks
The returned value is a screen space normalized rectangle, with values ranging from 0 to 1. To get actual safe area, scale it by screen width and height. i.e: screenSafeArea.scaleBy(screenWidth, screenHeight)
Gets the screen width of the screen surface the player is using.
Signature
screenWidth: ReadableHorizonProperty<number>;Remarks
The returned value is the size of the renderable screen width in pixels, and is not guaranteed to match the actual player's device screen width.
The multiplier applied to a player's locomotion speed when they are sprinting.
Signature
sprintMultiplier: HorizonProperty<number>;Examples
This example demonstrates how to modify the player sprint multiplier while it is inside a trigger.
class SprintMultiplierExample extends hz.Component<typeof SprintMultiplierExample> {
static propsDefinition = {
modifiedSprintMultiplier: { type: hz.PropTypes.Number },
};
private defaultSprintMultiplier: number = 1.4;
start() {
this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerEnterTrigger, (player) => {
player.sprintMultiplier.set(this.props.modifiedSprintMultiplier);
});
this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerExitTrigger, (player) => {
player.sprintMultiplier.set(this.defaultSprintMultiplier);
});
}
}
hz.Component.register(SprintMultiplierExample);Remarks
The default value is 1.4. The sprintMultiplier property must be a value between 1 and 10. Setting this to 1 disables a player's ability to sprint.sprintMultiplier.set can be called on any player from any context, but sprintMultiplier.get will throw an error unless it's called from a local script attached to an object owned by the player in question.
The multiplier applied to a player's locomotion speed when they are strafing.
Signature
strafeMultiplier: HorizonProperty<number>;Examples
This example demonstrates how to modify the player strafe multiplier while it is inside a trigger.
import * as hz from 'horizon/core';
class StrafeMultiplierExample extends hz.Component<typeof StrafeMultiplierExample> {
static propsDefinition = {
modifiedStrafeMultiplier: { type: hz.PropTypes.Number },
};
private defaultStrafeMultiplier: number = 0.825;
start() {
this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerEnterTrigger, (player) => {
var extendedPlayer = new hz.Player(player.id);
extendedPlayer.strafeMultiplier.set(this.props.modifiedStrafeMultiplier);
});
this.connectCodeBlockEvent(this.entity, hz.CodeBlockEvents.OnPlayerExitTrigger, (player) => {
var extendedPlayer = new hz.Player(player.id);
extendedPlayer.strafeMultiplier.set(this.defaultStrafeMultiplier);
});
}
}
hz.Component.register(StrafeMultiplierExample);Remarks
Default value is 0.825. strafeMultiplier must be a value between 0 and 10. strafeMultiplier.set can be called on any player from any context, but strafeMultiplier.get will throw an error unless it's called from a local script attached to an object owned by the player in question.Using the Orbit, Pan, and Follow camera modes will prevent the user from backpedaling.
The player's torso.
Signature
torso: PlayerBodyPart;The player's up direction relative to the world origin.
Signature
up: ReadableHorizonProperty<Vec3>;The player's velocity relative to the origin, in meters per second, due to physics and not locomotion input.
Signature
velocity: HorizonProperty<Vec3>;Overrides an avatar item on the player. Previous overrides are kept. Adds the new sku to the top of the existing list of overrides. Does not add if item is already in the list of overrides.
Signature
addAvatarOverride(sku: string): Promise<boolean>;Parameters
sku: string
Item sku to add
Returns
Promise<boolean>
- A promise that resolves to true if item is added successfully, false otherwise
Examples
playerA.addAvatarOverride(sku);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
Checks if an override can be applied to a player with collisions automatically remediated.
Signature
canApplyAvatarOverride(sku: string): Promise<boolean>;Parameters
sku: string
Item sku to override
Returns
Promise<boolean>
- A promise that resolves to true if item can be overridden successfully, false otherwise
Examples
playerA.canApplyAvatarOverride(sku);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.
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 .
Clears avatar item overrides on the player.
Signature
clearAvatarOverrides(): void;Returns
void
Examples
playerA.clearAvatarOverrides();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
Enables Focused Interaction mode for the player.
Signature
enterFocusedInteractionMode(options?: Partial<FocusedInteractionOptions>): void;Parameters
options: Partial<FocusedInteractionOptions>
(Optional) The options to customise the state of Focused Interaction mode. The DefaultFocusedInteractionEnableOptions variable defines the default values.
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.The Player.exitFocusedInteractionMode() method disables Focused Interaction mode.When Focused Interaction mode is enabled, you can receive input data from the PlayerControls.onFocusedInteractionInputStarted, PlayerControls.onFocusedInteractionInputMoved, and PlayerControls.onFocusedInteractionInputEnded events.For more information, see the Focused Interaction guide.
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 receive input data from the PlayerControls.onFocusedInteractionInputStarted, PlayerControls.onFocusedInteractionInputMoved, and PlayerControls.onFocusedInteractionInputEnded events.For more information, see the Focused Interaction guide.
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.
Gets the avatar item overrides on the player.
Signature
getAvatarOverrides(): Array<string>;Returns
Array<string>
- An Array of Item skus
Examples
playerA.getAvatarOverrides();Returns any available item traits associated with the player's avatar.
Signature
getAvatarTraits(): string;Returns
string
a JSON formatted-string with an array of objects for each item's traits
Examples
playerA.getAvatarTraits();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)
Issues a jump command.
Signature
jump(): Promise<LocomotionResult>;Returns
Promise<LocomotionResult>
A promise describing how the jump ended.
Issues a movement command to the player. Issuing a new move or follow command cancels any previous move command.
Signature
moveToPosition(position: Vec3, options?: LocomotionOptions): Promise<LocomotionResult>;Parameters
position: Vec3
The desired destination.
options: LocomotionOptions
(Optional) Optional parameters.
Returns
Promise<LocomotionResult>
- A promise describing how the locomotion ended.
Issues a movement command along a path. Issuing a new move or follow command cancels any previous move command.
Signature
moveToPositions(path: Array<Vec3>, options?: LocomotionOptions): Promise<LocomotionResult>;Parameters
path: Array<Vec3>
An array of points to follow, in order.
options: LocomotionOptions
(Optional) Optional parameters
Returns
Promise<LocomotionResult>
- A promise describing how the locomotion ended.
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.
Plays animations on the avatar as if locomoting according to the given options.
Signature
playAvatarAnimationLocomotion(options?: PlayAnimationLocomotionOptions): void;Parameters
options: PlayAnimationLocomotionOptions
(Optional) The options that control how to play the animation.
Returns
void
Remarks
This method allows you to animate the avatar as if locomoting a certain way.
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.
Removes an avatar item override on the player.
Signature
removeAvatarOverride(sku: string): boolean;Parameters
sku: string
Item sku to remove
Returns
boolean
- true if item is removed successfully, false otherwise. Will also return true if item was not in the list of overrides.
Examples
playerA.removeAvatarOverride(sku);Issues a rotation command to rotate the NPC by a given angle in degrees. Issuing a new rotate command cancels any previous rotate command.
Signature
rotateBy(angle: number, options?: RotationOptions): Promise<LocomotionResult>;Parameters
angle: number
The desired angle change in degrees.
options: RotationOptions
(Optional) Optional parameters.
Returns
Promise<LocomotionResult>
- A promise describing how the rotation ended.
Issues a rotation command to change the direction the player faces. Issuing a new rotate command cancels any previous rotate command.
Signature
rotateTo(direction: Vec3, options?: RotationOptions): Promise<LocomotionResult>;Parameters
direction: Vec3
The desired facing direction.
options: RotationOptions
(Optional) Optional parameters.
Returns
Promise<LocomotionResult>
- A promise describing how the rotation ended.
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)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.
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
Overrides avatar items on the player. Previous overrides are overwritten. Overrides of a different style (Such as a Fantastical avatar) will replace the user's Stylized avatar fully. If there are multiple skus for the same slot (eg top), priority is given to the first one in the array. Create Avatar items in the creator portal
Signature
setAvatarOverrides(skus: Array<string>): Promise<boolean>;Parameters
skus: Array<string>
Array of Item skus to override
Returns
Promise<boolean>
- A promise that resolves to true if items are added successfully, false otherwise
Examples
playerA.setAvatarOverrides([sku, anotherSku]);Sets Mobile Input control types to make the player sprint with minimal input on the joystickThe Threshold for sprinting is set at an input magnitude of 0.05This will provide a more responsive feel for fast-paced action oriented worldsHas no effect if set for a Player on VR or Web player Must be run on a local player
Signature
setMobileInputStyleAlwaysSprint(): void;Returns
void
Examples
start() {
const owner = this.owner.get();
if (owner.id != this.world.serverPlayer.get().id) {
var player = new hz.Player(this.entity.owner.get().id);
player?.setMobileInputStyleAlwaysSprint();
}
}Sets Mobile Input control types to a stepped curve This provides a more responsive feel to mobile players by using 1 of 3 specific movement magnitudes (walk/run/sprint)This allows players to have more fine control on tricky obstacles or small areas they might want to explore e.g. a lobby, or for navigation tightropes in a platforming game.Has no effect if set for a Player on VR or Web Must be run on a local player
Signature
setMobileInputStyleComfortable(walkThreshold?: number, runThreshold?: number, sprintThreshold?: number): void;Parameters
walkThreshold: number
(Optional) default 0.05
runThreshold: number
(Optional) default 0.4
sprintThreshold: number
(Optional) default 0.95
Returns
void
Examples
start() {
const owner = this.owner.get();
if (owner.id != this.world.serverPlayer.get().id) {
var player = new hz.Player(this.entity.owner.get().id);
player?.setMobileInputStyleComfortable();
}
}Sets Mobile Input control types to the default style This uses a linear gradient for speed relative to the joystick magnitude Has no effect if set for a Player on VR or Web Must be run on a local player
Signature
setMobileInputStyleDefault(): void;Returns
void
Examples
start() {
const owner = this.owner.get();
if (owner.id != this.world.serverPlayer.get().id) {
var player = new hz.Player(this.entity.owner.get().id);
player?.setMobileInputStyleDefault();
}
}Sets the VOIP setting for the player.
Signature
setVoipSetting(setting: VoipSetting): void;Parameters
setting: VoipSetting
The VOIP setting to use.
Returns
void
Shows info slides carousel for player.
Signature
showInfoSlides(slides: InfoSlide[]): void;Parameters
slides: InfoSlide[]
customized info slides that will be shown to the player
Returns
void
Initiates an attention-grabbing animation and displays a message above the on-screen button for a specified player input action. This is useful for button tooltips in timed action prompts and tutorials.
Signature
showInputActionMessage(inputAction: PlayerInputAction, message: i18n_utils.LocalizableText | string, duration?: number): void;Parameters
inputAction: PlayerInputAction
action for which we should show the NUX animation and message
message: i18n_utils.LocalizableText | string
localizable message that should be shown above the action button
duration: number
(Optional) duration in milliseconds for how long the message should be shown
Returns
void
Remarks
Mobile only.
Shows the toast message at the top of the screen.
Signature
showToastMessage(message: i18n_utils.LocalizableText | string, duration?: number): void;Parameters
message: i18n_utils.LocalizableText | string
localizable message that should be shown above the action button
duration: number
(Optional) duration in milliseconds for how long the message should be shown
Returns
void
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.
Stops any avatar animation locomotion overridden via the Player.playAvatarAnimationLocomotion() method.
Signature
stopAvatarAnimationLocomotion(): void;Returns
void
Stops any movement in progress.
Signature
stopMovement(): void;Returns
void
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
Creates a human-readable representation of the player.
Signature
toString(): string;Returns
string
A string representation of the player.
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.