Class Player

Represents a player within the world.

Hierarchy (View Summary)

Entity
- Player
  - SimulatedPlayer

Index

Properties

`Readonly`dimension

dimension: Dimension

Remarks

Dimension that the entity is currently within.

Throws

This property can throw when used.

`Readonly`id

id: string

Remarks

Unique identifier of the entity. This identifier is intended to be consistent across loads of a world instance. No meaning should be inferred from the value and structure of this unique identifier - do not parse or interpret it.

Throws

This property can throw when used.

`Beta`isSneaking

isSneaking: boolean

Remarks

Whether the entity is sneaking - that is, moving more slowly and more quietly.

This property can't be edited in read-only mode.

`Readonly` `Beta`level

level: number

Remarks

The current overall level for the player, based on their experience.

Throws

This property can throw when used.

`Readonly` `Beta`lifetimeState

lifetimeState: EntityLifetimeState

Remarks

Whether the entity reference that you have is valid or not. For example, an entity may be unloaded if it moves into a chunk that is unloaded, but may be reactivated if the chunk it is within gets reloaded.

`Readonly`location

location: Vector3

Remarks

Current location of the entity.

Throws

This property can throw when used.

`Readonly`name

name: string

Remarks

Name of the player.

Throws

This property can throw when used.

nameTag

nameTag: string

Remarks

Given name of the entity.

This property can't be edited in read-only mode.

`Readonly` `Beta`onScreenDisplay

onScreenDisplay: ScreenDisplay

Remarks

Contains methods for manipulating the on-screen display of a Player.

`Optional` `Readonly` `Beta`scoreboardIdentity

scoreboardIdentity?: ScoreboardIdentity

Remarks

Returns a scoreboard identity that represents this entity.

Throws

This property can throw when used.

`Beta`selectedSlot

selectedSlot: number

Remarks

Manages the selected slot in the player's hotbar.

This property can't be edited in read-only mode.

`Optional` `Readonly` `Beta`spawnDimension

spawnDimension?: Dimension

Remarks

If this player has an individual spawn point set, returns the dimension that their spawn point is within.

Throws

This property can throw when used.

`Readonly` `Beta`target

target: Entity

Remarks

Retrieves or sets an entity that is used as the target of AI-related behaviors, like attacking.

Throws

This property can throw when used.

`Readonly` `Beta`totalXpNeededForNextLevel

totalXpNeededForNextLevel: number

Remarks

The overall total set of experience needed to achieve the next level for a player.

Throws

This property can throw when used.

`Readonly`typeId

typeId: string

Remarks

Unique identifier of the type of the entity - for example, 'minecraft:skeleton'.

Throws

This property can throw when used.

`Readonly` `Beta`xpEarnedAtCurrentLevel

xpEarnedAtCurrentLevel: number

Remarks

The current set of experience achieved for the player.

Throws

This property can throw when used.

Methods

addEffect

addEffect(
    effectType: string | EffectType,
    duration: number,
    options?: EntityEffectOptions,
): boolean
Beta
Parameters
- effectType: string | EffectType
  Type of effect to add to the entity.
- duration: number
  Amount of time, in ticks, for the effect to apply. There are 20 ticks per second. Use TicksPerSecond constant to convert between ticks and seconds. The value must be within the range [0, 20000000].
- Optionaloptions: EntityEffectOptions
  Additional options for the effect.
Returns boolean
Returns nothing if the effect was added or updated successfully. This can throw an error if the duration or amplifier are outside of the valid ranges, or if the effect does not exist.
Remarks
Adds or updates an effect, like poison, to the entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.
Example: addEffect.js
```
const villagerId = 'minecraft:villager_v2<minecraft:ageable_grow_up>';
const villagerLoc: mc.Vector3 = { x: 1, y: 2, z: 1 };
const villager = test.spawn(villagerId, villagerLoc);
const duration = 20;

villager.addEffect(EffectTypes.get('poison'), duration, { amplifier: 1 });
```
Example: quickFoxLazyDog.ts
```
const fox = overworld.spawnEntity('minecraft:fox', {
    x: targetLocation.x + 1,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
});
fox.addEffect(mc.MinecraftEffectTypes.Speed, 10, { amplifier: 20 });
log('Created a fox.');

const wolf = overworld.spawnEntity('minecraft:wolf', {
    x: targetLocation.x + 4,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
});
wolf.addEffect(mc.MinecraftEffectTypes.Slowness, 10, { amplifier: 20 });
wolf.isSneaking = true;
log('Created a sneaking wolf.', 1);
```
Inherited from Entity.addEffect

addExperience

addExperience(amount: number): number
Beta
Parameters
- amount: number
  Amount of experience to add. Note that this can be negative.
Returns number
Returns the current experience of the Player.

Remarks
Adds/removes experience to/from the Player and returns the current experience of the Player.

This function can't be called in read-only mode.

Throws
This function can throw errors.

addLevels

addLevels(amount: number): number
Beta
Parameters
- amount: number
  Amount to add to the player.
Returns number
Returns the current level of the Player.

Remarks
Adds/removes level to/from the Player and returns the current level of the Player.

This function can't be called in read-only mode.

Throws
This function can throw errors.

addTag

addTag(tag: string): boolean
Parameters
- tag: string
  Content of the tag to add.
Returns boolean
Returns true if the tag was added successfully. This can fail if the tag already exists on the entity.

Remarks
Adds a specified tag to an entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.addTag

applyDamage

applyDamage(
amount: number,
options?: EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions,
): boolean
Parameters
- amount: number
  Amount of damage to apply.
- Optionaloptions: EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions
  Additional options about the source of damage, which may add additional effects or spur additional behaviors on this entity.
Returns boolean
Whether the entity takes any damage. This can return false if the entity is invulnerable or if the damage applied is less than or equal to 0.

Remarks
Applies a set of damage to an entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.applyDamage

applyImpulse

applyImpulse(vector: Vector3): void
Parameters
- vector: Vector3
  Impulse vector.
Returns void
Remarks
Applies impulse vector to the current velocity of the entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.applyImpulse

applyKnockback

applyKnockback(
    directionX: number,
    directionZ: number,
    horizontalStrength: number,
    verticalStrength: number,
): void
Parameters
- directionX: number
  X direction in horizontal plane.
- directionZ: number
  Z direction in horizontal plane.
- horizontalStrength: number
  Knockback strength for the horizontal vector.
- verticalStrength: number
  Knockback strength for the vertical vector.
Returns void
Remarks
Applies impulse vector to the current velocity of the entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.applyKnockback

clearSpawn

clearSpawn(): void
Beta
Returns void
Remarks
Clears the spawn point that has been individually set for a player.

This function can't be called in read-only mode.

Throws
This function can throw errors.

clearVelocity

clearVelocity(): void
Returns void
Remarks
Sets the current velocity of the Entity to zero. Note that this method may not have an impact on Players.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.clearVelocity

extinguishFire

extinguishFire(useEffects?: boolean): boolean
Beta
Parameters
- OptionaluseEffects: boolean
  Whether to show any visual effects connected to the extinguishing.
Returns boolean
Returns whether the entity was on fire.

Remarks
Extinguishes the fire if the entity is on fire. Note that you can call getComponent('minecraft:onfire') and, if present, the entity is on fire.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.extinguishFire

getBlockFromViewDirection

getBlockFromViewDirection(options?: BlockRaycastOptions): Block
Beta
Parameters
- Optionaloptions: BlockRaycastOptions
  Additional configuration options for the ray cast.
Returns Block
Returns the first intersecting block from the direction that this entity is looking at.

Remarks
Returns the first intersecting block from the direction that this entity is looking at.

Throws
This function can throw errors.

Inherited from Entity.getBlockFromViewDirection

getComponent

getComponent(componentId: string): undefined | EntityComponent
Parameters
- componentId: string
  The identifier of the component (e.g., 'minecraft:rideable') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed. If the component is not present on the entity, undefined is returned.
Returns undefined | EntityComponent
Returns the component if it exists on the entity, otherwise undefined.

Remarks
Gets a component (that represents additional capabilities) for an entity.

Inherited from Entity.getComponent

getComponents

getComponents(): EntityComponent[]
Returns EntityComponent[]
Returns all components that are both present on this entity and supported by the API.

Remarks
Returns all components that are both present on this entity and supported by the API.

Inherited from Entity.getComponents

getDynamicProperty

getDynamicProperty(identifier: string): undefined | string | number | boolean
Beta
Parameters
- identifier: string
  The property identifier.
Returns undefined | string | number | boolean
Returns the value for the property, or undefined if the property has not been set.

Remarks
Returns a property value.

Throws
This function can throw errors.

Inherited from Entity.getDynamicProperty

getEffect

getEffect(effectType: string | EffectType): undefined | Effect
Beta
Parameters
- effectType: string | EffectType
  The effect identifier.
Returns undefined | Effect
Effect object for the specified effect, undefined if the effect is not present, or throws an error if the effect does not exist.

Remarks
Returns the effect for the specified EffectType on the entity, undefined if the effect is not present, or throws an error if the effect does not exist.

Throws
This function can throw errors.

Inherited from Entity.getEffect

getEffects

getEffects(): Effect[]
Beta
Returns Effect[]
List of effects.

Remarks
Returns a set of effects applied to this entity.

Throws
This function can throw errors.

Inherited from Entity.getEffects

getEntitiesFromViewDirection

getEntitiesFromViewDirection(options?: EntityRaycastOptions): Entity[]
Beta
Parameters
- Optionaloptions: EntityRaycastOptions
  Additional configuration options for the ray cast.
Returns Entity[]
Returns a set of entities from the direction that this entity is looking at.

Remarks
Gets the entities that this entity is looking at by performing a ray cast from the view of this entity.

Throws
This function can throw errors.

Inherited from Entity.getEntitiesFromViewDirection

getHeadLocation

getHeadLocation(): Vector3
Returns Vector3
Returns the current location of the head component of this entity.

Remarks
Returns the current location of the head component of this entity.

Throws
This function can throw errors.

Inherited from Entity.getHeadLocation

getItemCooldown

getItemCooldown(itemCategory: string): number
Beta
Parameters
- itemCategory: string
  Specifies the cooldown category to retrieve the current cooldown for.
Returns number
Remarks
Gets the current item cooldown time for a particular cooldown category.

Throws
This function can throw errors.

getRotation

getRotation(): Vector2
Beta
Returns Vector2
Returns the current rotation component of this entity.

Remarks
Returns the current rotation component of this entity.

Throws
This function can throw errors.

Inherited from Entity.getRotation

getSpawnPosition

getSpawnPosition(): undefined | Vector3
Beta
Returns undefined | Vector3
The individual spawn position, or undefined if there is no specific spawn position set for a player.

Remarks
Returns an individualized spawn position, if set, for a player.

Throws
This function can throw errors.

getTags

getTags(): string[]
Returns string[]
Returns the current rotation component of this entity.

Remarks
Returns all tags associated with an entity.

Throws
This function can throw errors.

Inherited from Entity.getTags

getTotalXp

getTotalXp(): number
Beta
Returns number
Remarks
Gets the total experience of the Player.

Throws
This function can throw errors.

getVelocity

getVelocity(): Vector3
Returns Vector3
Returns the current velocity vector of the entity.

Remarks
Returns the current velocity vector of the entity.

Throws
This function can throw errors.

Inherited from Entity.getVelocity

getViewDirection

getViewDirection(): Vector3
Returns Vector3
Returns the current view direction of the entity.

Remarks
Returns the current view direction of the entity.

Throws
This function can throw errors.

Inherited from Entity.getViewDirection

hasComponent

hasComponent(componentId: string): boolean
Parameters
- componentId: string
  The identifier of the component (e.g., 'minecraft:rideable') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.
Returns boolean
Returns true if the specified component is present on this entity.

Remarks
Returns true if the specified component is present on this entity.

Inherited from Entity.hasComponent

hasTag

hasTag(tag: string): boolean
Parameters
- tag: string
  Identifier of the tag to test for.
Returns boolean
Returns whether an entity has a particular tag.

Remarks
Returns whether an entity has a particular tag.

Throws
This function can throw errors.

Inherited from Entity.hasTag

isOp

isOp(): boolean
Beta
Returns boolean
Remarks
Returns true if this player has operator-level permissions.

Throws
This function can throw errors.

kill

kill(): boolean
Returns boolean
Returns true if entity can be killed (even if it is already dead), otherwise it returns false.

Remarks
Kills this entity. The entity will drop loot as normal.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.kill

playAnimation

playAnimation(animationName: string, options?: PlayAnimationOptions): void
Beta
Parameters
- animationName: string
  The animation identifier. e.g. animation.creeper.swelling
- Optionaloptions: PlayAnimationOptions
  Additional options to control the playback and transitions of the animation.
Returns void
Remarks
Cause the entity to play the given animation.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.playAnimation

playSound

playSound(soundID: string, soundOptions?: PlayerSoundOptions): void
Parameters
- soundID: string
  Identifier of the sound to play.
- OptionalsoundOptions: PlayerSoundOptions
  Additional optional options for the sound.
Returns void
Remarks
Plays a sound that only this particular player can hear.

This function can't be called in read-only mode.

Throws
This function can throw errors.

postClientMessage

postClientMessage(id: string, value: string): void
Beta
Parameters
- id: string
- value: string
Returns void
Remarks
This is an internal-facing method for posting a system message to downstream clients.

This function can't be called in read-only mode.

Throws
This function can throw errors.

removeDynamicProperty

removeDynamicProperty(identifier: string): boolean
Beta
Parameters
- identifier: string
  The property identifier.
Returns boolean
Returns whether the given property existed on the entity.

Remarks
Removes a specified property.

Throws
This function can throw errors.

Inherited from Entity.removeDynamicProperty

removeEffect

removeEffect(effectType: string | EffectType): boolean
Beta
Parameters
- effectType: string | EffectType
  The effect identifier.
Returns boolean
Returns true if the effect has been removed, false if the effect is not present, or will throw an error if the effect does not exist.

Remarks
Removes the specified EffectType on the entity, or returns false if the effect is not present.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.removeEffect

removeTag

removeTag(tag: string): boolean
Parameters
- tag: string
  Content of the tag to remove.
Returns boolean
Returns whether the tag existed on the entity.

Remarks
Removes a specified tag from an entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.removeTag

resetLevel

resetLevel(): void
Beta
Returns void
Remarks
Resets the level of the player.

This function can't be called in read-only mode.

Throws
This function can throw errors.

runCommand

runCommand(commandString: string): CommandResult
Parameters
- commandString: string
  The command string. Note: This should not include a leading forward slash.
Returns CommandResult
A command result containing whether the command was successful.

Remarks
Runs a synchronous command on the entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.runCommand

runCommandAsync

runCommandAsync(commandString: string): Promise<CommandResult>
Parameters
- commandString: string
  Command to run. Note that command strings should not start with slash.
Returns Promise<CommandResult>
For commands that return data, returns a JSON structure with command response values.

Remarks
Runs a particular command asynchronously from the context of this entity. Note that there is a maximum queue of 128 asynchronous commands that can be run in a given tick.

Throws
This function can throw errors.

Inherited from Entity.runCommandAsync

sendMessage

sendMessage(message: string | RawMessage | (string | RawMessage)[]): void

Parameters

message: string | RawMessage | (string | RawMessage)[]
The message to be displayed.

Returns void

Remarks

Sends a message to the player.

Throws

This method can throw if the provided RawMessage is in an invalid format. For example, if an empty name string is provided to score.

Example: nestedTranslation.ts

// Displays "Apple or Coal"
let rawMessage = {
  translate: "accessibility.list.or.two",
  with: { rawtext: [{ translate: "item.apple.name" }, { translate: "item.coal.name" }] },
};
player.sendMessage(rawMessage);

Example: scoreWildcard.ts

// Displays the player's score for objective "obj". Each player will see their own score.
const rawMessage = { score: { name: "*", objective: "obj" } };
world.sendMessage(rawMessage);

Example: simpleString.ts

// Displays "Hello, world!"
world.sendMessage("Hello, world!");

Example: translation.ts

// Displays "First or Second"
const rawMessage = { translate: "accessibility.list.or.two", with: ["First", "Second"] };
player.sendMessage(rawMessage);

setDynamicProperty

setDynamicProperty(identifier: string, value: string | number | boolean): void
Beta
Parameters
- identifier: string
  The property identifier.
- value: string | number | boolean
  Data value of the property to set.
Returns void
Remarks
Sets a specified property to a value.

Throws
This function can throw errors.

Inherited from Entity.setDynamicProperty

setOnFire

setOnFire(seconds: number, useEffects?: boolean): boolean
Beta
Parameters
- seconds: number
  Length of time to set the entity on fire.
- OptionaluseEffects: boolean
  Whether side-effects should be applied (e.g. thawing freeze) and other conditions such as rain or fire protection should be taken into consideration.
Returns boolean
Whether the entity was set on fire. This can fail if seconds is less than or equal to zero, the entity is wet or the entity is immune to fire.

Remarks
Sets an entity on fire (if it is not in water or rain). Note that you can call getComponent('minecraft:onfire') and, if present, the entity is on fire.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.setOnFire

setOp

setOp(isOp: boolean): void
Beta
Parameters
- isOp: boolean
Returns void
Remarks
Will change the specified players permissions, and whether they are operator or not.

This function can't be called in read-only mode.

Throws
This function can throw errors.

setRotation

setRotation(rotation: Vector2): void
Beta
Parameters
- rotation: Vector2
  The x and y rotation of the entity. For most mobs, the x rotation controls the head tilt and the y rotation controls the body rotation.
Returns void
Remarks
Sets the main rotation of the entity.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.setRotation

setSpawn

setSpawn(spawnPosition: Vector3, spawnDimension: Dimension): void
Beta
Parameters
- spawnPosition: Vector3
  Location of the spawn point.
- spawnDimension: Dimension
  Dimension to place the players' individualized spawn point within.
Returns void
Returns undefined/void.

Remarks
Sets the individual spawn point of this player.

This function can't be called in read-only mode.

Throws
This function can throw errors.

startItemCooldown

startItemCooldown(itemCategory: string, tickDuration: number): void
Beta
Parameters
- itemCategory: string
  Specifies the cooldown category to retrieve the current cooldown for.
- tickDuration: number
  Duration in ticks of the item cooldown.
Returns void
Remarks
Sets the item cooldown time for a particular cooldown category.

This function can't be called in read-only mode.

Throws
This function can throw errors.

teleport

teleport(location: Vector3, teleportOptions?: TeleportOptions): void
Beta
Parameters
- location: Vector3
  New location for the entity.
- OptionalteleportOptions: TeleportOptions
  Options regarding the teleport operation.
Returns void
Remarks
Teleports the selected entity to a new location

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.teleport

triggerEvent

triggerEvent(eventName: string): void
Beta
Parameters
- eventName: string
  Name of the entity type event to trigger. If a namespace is not specified, minecraft: is assumed.
Returns void
Remarks
Triggers an entity type event. For every entity, a number of events are defined in an entities' definition for key entity behaviors; for example, creepers have a minecraft:start_exploding type event.

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.triggerEvent

tryTeleport

tryTeleport(location: Vector3, teleportOptions?: TeleportOptions): boolean
Beta
Parameters
- location: Vector3
  Location to teleport the entity to.
- OptionalteleportOptions: TeleportOptions
  Options regarding the teleport operation.
Returns boolean
Returns whether the teleport succeeded. This can fail if the destination chunk is unloaded or if the teleport would result in intersecting with blocks.

Remarks
Attempts to try a teleport, but may not complete the teleport operation (for example, if there are blocks at the destination.)

This function can't be called in read-only mode.

Throws
This function can throw errors.

Inherited from Entity.tryTeleport

Class Player

Hierarchy (View Summary)

Index

Properties

Methods

Properties

Readonlydimension

Remarks

Throws

Readonlyid

Remarks

Throws

BetaisSneaking

Remarks

Readonly Betalevel

Remarks

Throws

Readonly BetalifetimeState

Remarks

Readonlylocation

Remarks

Throws

Readonlyname

Remarks

Throws

nameTag

Remarks

Readonly BetaonScreenDisplay

Remarks

Optional Readonly BetascoreboardIdentity

Remarks

Throws

BetaselectedSlot

Remarks

Optional Readonly BetaspawnDimension

Remarks

Throws

Readonly Betatarget

Remarks

Throws

Readonly BetatotalXpNeededForNextLevel

Remarks

Throws

ReadonlytypeId

Remarks

Throws

Readonly BetaxpEarnedAtCurrentLevel

Remarks

Throws

Methods

addEffect

Parameters

Returns boolean

Remarks

Throws

Example: addEffect.js

Example: quickFoxLazyDog.ts

addExperience

Parameters

Returns number

Remarks

Throws

addLevels

Parameters

Returns number

Remarks

Throws

addTag

Parameters

Returns boolean

Remarks

Throws

applyDamage

Parameters

Returns boolean

Remarks

Throws

applyImpulse

Parameters

Returns void

`Readonly`dimension

`Readonly`id

`Beta`isSneaking

`Readonly` `Beta`level

`Readonly` `Beta`lifetimeState

`Readonly`location

`Readonly`name

`Readonly` `Beta`onScreenDisplay

`Optional` `Readonly` `Beta`scoreboardIdentity

`Beta`selectedSlot

`Optional` `Readonly` `Beta`spawnDimension

`Readonly` `Beta`target

`Readonly` `Beta`totalXpNeededForNextLevel

`Readonly`typeId

`Readonly` `Beta`xpEarnedAtCurrentLevel