@minecraft/server-gametest / SimulatedPlayer

Class: SimulatedPlayer

Defined in: @minecraft/server-gametest/index.d.ts:473

Beta

A simulated player can be used within GameTests to represent how a player moves throughout the world and to support testing of how entities and the environment will react to a player. This type derives much of its structure and methods from the minecraftserver.Player type. Note that many types of events that may be available for entities more broadly, such as item use events, may not fire in the same capacity for simulated players.

Extends

Player

Properties

camera

readonly camera: Camera

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12368

Beta

Remarks

The player's Camera.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.camera

clientSystemInfo

readonly clientSystemInfo: ClientSystemInfo

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12375

Beta

Remarks

Contains the player's device information.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.clientSystemInfo

dimension

readonly dimension: Dimension

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6080

Beta

Remarks

Dimension that the entity is currently within.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.dimension

headRotation

readonly headRotation: Vector2

Defined in: @minecraft/server-gametest/index.d.ts:481

Beta

Remarks

Rotation of the head across pitch and yaw angles.

Throws

This property can throw when used.

id

readonly id: string

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6091

Beta

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. This property is accessible even if Entity.isValid is false.

Inherited from

minecraftserver.Player.id

inputInfo

readonly inputInfo: InputInfo

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12381

Beta

Remarks

Contains the player's input information.

Inherited from

minecraftserver.Player.inputInfo

inputPermissions

readonly inputPermissions: PlayerInputPermissions

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12387

Beta

Remarks

Input permissions of the player.

Inherited from

minecraftserver.Player.inputPermissions

isClimbing

readonly isClimbing: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6100

Beta

Remarks

Whether the entity is touching a climbable block. For example, a player next to a ladder or a spider next to a stone wall.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isClimbing

isEmoting

readonly isEmoting: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12394

Beta

Remarks

If true, the player is currently emoting.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isEmoting

isFalling

readonly isFalling: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6108

Beta

Remarks

Whether the entity has a fall distance greater than 0, or greater than 1 while gliding.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isFalling

isFlying

readonly isFlying: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12402

Beta

Remarks

Whether the player is flying. For example, in Creative or Spectator mode.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isFlying

isGliding

readonly isGliding: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12409

Beta

Remarks

Whether the player is gliding with Elytra.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isGliding

isInWater

readonly isInWater: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6115

Beta

Remarks

Whether any part of the entity is inside a water block.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isInWater

isJumping

readonly isJumping: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12417

Beta

Remarks

Whether the player is jumping. This will remain true while the player is holding the jump action.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isJumping

isOnGround

readonly isOnGround: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6125

Beta

Remarks

Whether the entity is on top of a solid block. This property may behave in unexpected ways. This property will always be true when an Entity is first spawned, and if the Entity has no gravity this property may be incorrect.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isOnGround

isSleeping

readonly isSleeping: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6132

Beta

Remarks

If true, the entity is currently sleeping.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isSleeping

isSneaking

isSneaking: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6141

Beta

Remarks

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

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

Inherited from

minecraftserver.Player.isSneaking

isSprinting

isSprinting: boolean

Defined in: @minecraft/server-gametest/index.d.ts:489

Beta

Remarks

Returns whether the simulated player is sprinting.

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

Overrides

minecraftserver.Player.isSprinting

isSwimming

readonly isSwimming: boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6158

Beta

Remarks

Whether the entity is in the swimming state. For example, a player using the swim action or a fish in water.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.isSwimming

level

readonly level: number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12425

Beta

Remarks

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

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.level

location

readonly location: Vector3

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6165

Beta

Remarks

Current location of the entity.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.location

name

readonly name: string

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12432

Beta

Remarks

Name of the player.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.name

nameTag

nameTag: string

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6173

Beta

Remarks

Given name of the entity.

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

Inherited from

minecraftserver.Player.nameTag

onScreenDisplay

readonly onScreenDisplay: ScreenDisplay

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12440

Beta

Remarks

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

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.onScreenDisplay

scoreboardIdentity?

readonly optional scoreboardIdentity?: ScoreboardIdentity

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6180

Beta

Remarks

Returns a scoreboard identity that represents this entity. Will remain valid when the entity is killed.

Inherited from

minecraftserver.Player.scoreboardIdentity

selectedSlotIndex

selectedSlotIndex: number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12446

Beta

Remarks

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

Inherited from

minecraftserver.Player.selectedSlotIndex

totalXpNeededForNextLevel

readonly totalXpNeededForNextLevel: number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12454

Beta

Remarks

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

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.totalXpNeededForNextLevel

typeId

readonly typeId: string

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6188

Beta

Remarks

Identifier of the type of the entity - for example, 'minecraft:skeleton'. This property is accessible even if Entity.isValid is false.

Inherited from

minecraftserver.Player.typeId

xpEarnedAtCurrentLevel

readonly xpEarnedAtCurrentLevel: number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12461

Beta

Remarks

The current set of experience achieved for the player.

Throws

This property can throw when used.

Inherited from

minecraftserver.Player.xpEarnedAtCurrentLevel

Methods

addEffect()

addEffect(effectType, duration, options?): Effect | undefined

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6255

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

options?

EntityEffectOptions

Additional options for the effect.

Returns

Effect | undefined

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.

Examples

spawnPoisonedVillager.ts

typescript

import { DimensionLocation } from "@minecraft/server";
import { MinecraftEffectTypes } from "@minecraft/vanilla-data";

function spawnPoisonedVillager(
    targetLocation: DimensionLocation
) {
  const villagerType = "minecraft:villager_v2&lt;minecraft:ageable_grow_up&gt;";
  const villager = targetLocation.dimension.spawnEntity(villagerType, targetLocation);
  const duration = 20;

  villager.addEffect(MinecraftEffectTypes.Poison, duration, { amplifier: 1 });
}

quickFoxLazyDog.ts

typescript

import { DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes, MinecraftEffectTypes } from "@minecraft/vanilla-data";

function quickFoxLazyDog(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const fox = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Fox, {
    x: targetLocation.x + 1,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
  });

  fox.addEffect(MinecraftEffectTypes.Speed, 10, {
    amplifier: 2,
  });
  log("Created a fox.");

  const wolf = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Wolf, {
    x: targetLocation.x + 4,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
  });
  wolf.addEffect(MinecraftEffectTypes.Slowness, 10, {
    amplifier: 2,
  });
  wolf.isSneaking = true;
  log("Created a sneaking wolf.", 1);
}

Inherited from

minecraftserver.Player.addEffect

addExperience()

addExperience(amount): number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12476

Beta

Parameters

amount

number

Amount of experience to add. Note that this can be negative. Min/max bounds at -2^24 ~ 2^24

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.

Inherited from

minecraftserver.Player.addExperience

addLevels()

addLevels(amount): number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12490

Beta

Parameters

amount

number

Amount to add to the player. Min/max bounds at -2^24 ~ 2^24

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.

Inherited from

minecraftserver.Player.addLevels

addTag()

addTag(tag): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6293

Beta

Parameters

tag

string

Content of the tag to add. The tag must be less than 256 characters.

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.

Example

tagsQuery.ts

typescript

import { EntityQueryOptions, DimensionLocation } from "@minecraft/server";

function tagsQuery(targetLocation: DimensionLocation) {
  const mobs = ["creeper", "skeleton", "sheep"];

  // create some sample mob data
  for (let i = 0; i < 10; i++) {
    const mobTypeId = mobs[i % mobs.length];
    const entity = targetLocation.dimension.spawnEntity(mobTypeId, targetLocation);
    entity.addTag("mobparty." + mobTypeId);
  }

  const eqo: EntityQueryOptions = {
    tags: ["mobparty.skeleton"],
  };

  for (const entity of targetLocation.dimension.getEntities(eqo)) {
    entity.kill();
  }
}

Inherited from

minecraftserver.Player.addTag

applyDamage()

applyDamage(amount, options?): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6333

Beta

Parameters

amount

number

Amount of damage to apply.

options?

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.

Example

applyDamageThenHeal.ts

typescript

import { system, EntityHealthComponent, EntityComponentTypes, DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function applyDamageThenHeal(
  log: (message: string, status?: number) => void,
  targetLocation: DimensionLocation
) {
  const skelly = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Skeleton, targetLocation);

  skelly.applyDamage(19); // skeletons have max damage of 20 so this is a near-death skeleton

  system.runTimeout(() => {
    const health = skelly.getComponent(EntityComponentTypes.Health) as EntityHealthComponent;
    log("Skeleton health before heal: " + health?.currentValue);
    health?.resetToMaxValue();
    log("Skeleton health after heal: " + health?.currentValue);
  }, 20);
}

Inherited from

minecraftserver.Player.applyDamage

applyImpulse()

applyImpulse(vector): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6359

Beta

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.

Example

applyImpulse.ts

typescript

import { DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function applyImpulse(targetLocation: DimensionLocation) {
  const zombie = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Zombie, targetLocation);

  zombie.clearVelocity();

  // throw the zombie up in the air
  zombie.applyImpulse({ x: 0, y: 0.5, z: 0 });
}

Inherited from

minecraftserver.Player.applyImpulse

applyKnockback()

applyKnockback(directionX, directionZ, horizontalStrength, verticalStrength): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6398

Beta

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.

Example

bounceSkeletons.ts

typescript

import { EntityQueryOptions, DimensionLocation } from "@minecraft/server";

function bounceSkeletons(targetLocation: DimensionLocation) {
  const mobs = ["creeper", "skeleton", "sheep"];

  // create some sample mob data
  for (let i = 0; i < 10; i++) {
    targetLocation.dimension.spawnEntity(mobs[i % mobs.length], targetLocation);
  }

  const eqo: EntityQueryOptions = {
    type: "skeleton",
  };

  for (const entity of targetLocation.dimension.getEntities(eqo)) {
    entity.applyKnockback(0, 0, 0, 1);
  }
}

Inherited from

minecraftserver.Player.applyKnockback

attack()

attack(): boolean

Defined in: @minecraft/server-gametest/index.d.ts:501

Beta

Returns

boolean

Remarks

Causes the simulated player to make an attack 'swipe'. Returns true if the attack was performed - for example, the player was not on cooldown and had a valid target. Target selection is performed by raycasting from the player's head.

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

Throws

This function can throw errors.

attackEntity()

attackEntity(entity): boolean

Defined in: @minecraft/server-gametest/index.d.ts:514

Beta

Parameters

entity

Entity

Returns

boolean

Remarks

Causes the simulated player to attack the provided target. Returns true if the attack was performed - for example, the player was not on cooldown and had a valid target. The attack can be performed at any distance and does not require line of sight to the target entity.

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

Throws

This function can throw errors.

breakBlock()

breakBlock(blockLocation, direction?): boolean

Defined in: @minecraft/server-gametest/index.d.ts:530

Beta

Parameters

blockLocation

Vector3

Location of the block to interact with.

direction?

Direction

Direction to place the specified item within.

Returns

boolean

Remarks

Destroys the block at blockLocation, respecting the rules of the server player's game mode. The block will be hit until broken, an item is used or stopBreakingBlock is called. Returns true if the block at blockLocation is solid.

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

Throws

This function can throw errors.

chat()

chat(message): void

Defined in: @minecraft/server-gametest/index.d.ts:537

Beta

Parameters

message

string

Returns

void

Remarks

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

Throws

This function can throw errors.

clearDynamicProperties()

clearDynamicProperties(): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6406

Beta

Returns

void

Remarks

Clears all dynamic properties that have been set on this entity.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.clearDynamicProperties

clearPropertyOverridesForEntity()

clearPropertyOverridesForEntity(targetEntity): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12505

Beta

Parameters

targetEntity

Entity

The Entity whose Entity Property overrides are being cleared.

Returns

void

Remarks

For this player, removes all overrides of any Entity Properties on the target Entity. This change is not applied until the next tick and will not apply to other players.

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

Throws

Throws if the entity is invalid.

Inherited from

minecraftserver.Player.clearPropertyOverridesForEntity

clearVelocity()

clearVelocity(): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6430

Beta

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.

Example

applyImpulse.ts

typescript

import { DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function applyImpulse(targetLocation: DimensionLocation) {
  const zombie = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Zombie, targetLocation);

  zombie.clearVelocity();

  // throw the zombie up in the air
  zombie.applyImpulse({ x: 0, y: 0.5, z: 0 });
}

Inherited from

minecraftserver.Player.clearVelocity

disconnect()

disconnect(): void

Defined in: @minecraft/server-gametest/index.d.ts:547

Beta

Returns

void

Remarks

Simulates and performs a disconnection of the simulated player from the world.

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

Throws

This function can throw errors.

dropSelectedItem()

dropSelectedItem(): boolean

Defined in: @minecraft/server-gametest/index.d.ts:556

Beta

Returns

boolean

Remarks

Drops the simulated player's selected item

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

Throws

This function can throw errors.

extinguishFire()

extinguishFire(useEffects?): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6466

Beta

Parameters

useEffects?

boolean

Whether to show any visual effects connected to the extinguishing. Defaults to: true

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.

Example

setOnFire.ts

typescript

import { system, EntityOnFireComponent, EntityComponentTypes, DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function setOnFire(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const skelly = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Skeleton, targetLocation);

  skelly.setOnFire(20, true);

  system.runTimeout(() => {
    const onfire = skelly.getComponent(EntityComponentTypes.OnFire) as EntityOnFireComponent;
    log(onfire?.onFireTicksRemaining + " fire ticks remaining.");

    skelly.extinguishFire(true);
    log("Never mind. Fire extinguished.");
  }, 20);
}

Inherited from

minecraftserver.Player.extinguishFire

fly()

fly(): void

Defined in: @minecraft/server-gametest/index.d.ts:567

Beta

Returns

void

Remarks

Causes the simulated player to start flying as though they were flying in creative mode. For flying with Elytra, see function glide.

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

Throws

This function can throw errors.

getBlockFromViewDirection()

getBlockFromViewDirection(options?): BlockRaycastHit | undefined

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6479

Beta

Parameters

options?

BlockRaycastOptions

Additional configuration options for the ray cast.

Returns

BlockRaycastHit | undefined

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

minecraftserver.Player.getBlockFromViewDirection

getComponent()

getComponent<T>(componentId): EntityComponentReturnType<T> | undefined

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6494

Beta

Type Parameters

T

T extends string

Parameters

componentId

T

The identifier of the component (e.g., 'minecraft:health'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs can be found as part of the EntityComponentTypes enum.

Returns

EntityComponentReturnType<T> | undefined

Returns the component if it exists on the entity, otherwise undefined.

Remarks

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

Inherited from

minecraftserver.Player.getComponent

getComponents()

getComponents(): EntityComponent[]

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6504

Beta

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

minecraftserver.Player.getComponents

getDynamicProperty()

getDynamicProperty(identifier): string | number | boolean | Vector3 | undefined

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6516

Beta

Parameters

identifier

string

The property identifier.

Returns

string | number | boolean | Vector3 | undefined

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

minecraftserver.Player.getDynamicProperty

getDynamicPropertyIds()

getDynamicPropertyIds(): string[]

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6526

Beta

Returns

string[]

A string array of the dynamic properties set on this entity.

Remarks

Returns the available set of dynamic property identifiers that have been used on this entity.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getDynamicPropertyIds

getDynamicPropertyTotalByteCount()

getDynamicPropertyTotalByteCount(): number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6538

Beta

Returns

number

Remarks

Returns the total size, in bytes, of all the dynamic properties that are currently stored for this entity. This includes the size of both the key and the value. This can be useful for diagnosing performance warning signs - if, for example, an entity has many megabytes of associated dynamic properties, it may be slow to load on various devices.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getDynamicPropertyTotalByteCount

getEffect()

getEffect(effectType): Effect | undefined

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6553

Beta

Parameters

effectType

string | EffectType

The effect identifier.

Returns

Effect | undefined

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

minecraftserver.Player.getEffect

getEffects()

getEffects(): Effect[]

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6562

Beta

Returns

Effect[]

List of effects.

Remarks

Returns a set of effects applied to this entity.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getEffects

getEntitiesFromViewDirection()

getEntitiesFromViewDirection(options?): EntityRaycastHit[]

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6575

Beta

Parameters

options?

EntityRaycastOptions

Additional configuration options for the ray cast.

Returns

EntityRaycastHit[]

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

minecraftserver.Player.getEntitiesFromViewDirection

getGameMode()

getGameMode(): GameMode

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12512

Beta

Returns

GameMode

Remarks

Retrieves the active gamemode for this player, if specified.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getGameMode

getHeadLocation()

getHeadLocation(): Vector3

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6586

Beta

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

minecraftserver.Player.getHeadLocation

getItemCooldown()

getItemCooldown(cooldownCategory): number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12523

Beta

Parameters

cooldownCategory

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.

Inherited from

minecraftserver.Player.getItemCooldown

getProperty()

getProperty(identifier): string | number | boolean | undefined

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6603

Beta

Parameters

identifier

string

The entity Property identifier.

Returns

string | number | boolean | undefined

Returns the current property value. For enum properties, a string is returned. For float and int properties, a number is returned. For undefined properties, undefined is returned.

Remarks

Gets an entity Property value. If the property was set using the setProperty function within the same tick, the updated value will not be reflected until the subsequent tick.

Throws

Throws if the entity is invalid.

Inherited from

minecraftserver.Player.getProperty

getRotation()

getRotation(): Vector2

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6613

Beta

Returns

Vector2

Returns a Vec2 containing the rotation of this entity (in degrees).

Remarks

Returns the current rotation component of this entity.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getRotation

getSpawnPoint()

getSpawnPoint(): DimensionLocation | undefined

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12530

Beta

Returns

DimensionLocation | undefined

Remarks

Gets the current spawn point of the player.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getSpawnPoint

getTags()

getTags(): string[]

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6622

Beta

Returns

string[]

An array containing all tags as strings.

Remarks

Returns all tags associated with the entity.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getTags

getTotalXp()

getTotalXp(): number

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12537

Beta

Returns

number

Remarks

Gets the total experience of the Player.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.getTotalXp

getVelocity()

getVelocity(): Vector3

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6649

Beta

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.

Example

getFireworkVelocity.ts

typescript

import { system, DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function getFireworkVelocity(
  log: (message: string, status?: number) => void,
  targetLocation: DimensionLocation
) {
  const fireworkRocket = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.FireworksRocket, targetLocation);

  system.runTimeout(() => {
    const velocity = fireworkRocket.getVelocity();

    log("Velocity of firework is: (x: " + velocity.x + ", y:" + velocity.y + ", z:" + velocity.z + ")");
  }, 5);
}

Inherited from

minecraftserver.Player.getVelocity

getViewDirection()

getViewDirection(): Vector3

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6658

Beta

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

minecraftserver.Player.getViewDirection

giveItem()

giveItem(itemStack, selectSlot?): boolean

Defined in: @minecraft/server-gametest/index.d.ts:580

Beta

Parameters

itemStack

ItemStack

Item to give.

selectSlot?

boolean

Whether to set the selected slot once given.

Returns

boolean

Remarks

Gives the simulated player a particular item stack.

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

Throws

This function can throw errors.

glide()

glide(): boolean

Defined in: @minecraft/server-gametest/index.d.ts:595

Beta

Returns

boolean

Returns true if the simulated player begins to glide. Returns false if the player is already gliding, or the player does not have Elytra equipped, is in water or is on the ground.

Remarks

Causes the simulated player to start gliding. Elytra must be equipped and the player must be in the air.

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

Throws

This function can throw errors.

hasComponent()

hasComponent(componentId): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6672

Beta

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

minecraftserver.Player.hasComponent

hasTag()

hasTag(tag): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6683

Beta

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

minecraftserver.Player.hasTag

interact()

interact(): boolean

Defined in: @minecraft/server-gametest/index.d.ts:606

Beta

Returns

boolean

Remarks

Performs a raycast from the player’s head and interacts with the first intersected block or entity. Returns true if the interaction was successful. Maximum range is 6 blocks.

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

Throws

This function can throw errors.

interactWithBlock()

interactWithBlock(blockLocation, direction?): boolean

Defined in: @minecraft/server-gametest/index.d.ts:621

Beta

Parameters

blockLocation

Vector3

Location of the block to interact with.

direction?

Direction

Direction to place the specified item within.

Returns

boolean

Remarks

Causes the simulated player to interact with a block. The block at the specified block location must be solid. Returns true if the interaction was performed.

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

Throws

This function can throw errors.

interactWithEntity()

interactWithEntity(entity): boolean

Defined in: @minecraft/server-gametest/index.d.ts:633

Beta

Parameters

entity

Entity

Entity to interact with.

Returns

boolean

Remarks

Causes the simulated player to interact with a mob. Returns true if the interaction was performed.

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

Throws

This function can throw errors.

isValid()

isValid(): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6695

Beta

Returns

boolean

Whether the entity is valid.

Deprecated

This function is deprecated and will be removed in 2.0.0.

Remarks

Returns whether the entity can be manipulated by script. A Player is considered valid when it's EntityLifetimeState is set to Loaded.

Inherited from

minecraftserver.Player.isValid

jump()

jump(): boolean

Defined in: @minecraft/server-gametest/index.d.ts:644

Beta

Returns

boolean

True if a jump was performed.

Remarks

Causes the simulated player to jump.

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

Throws

This function can throw errors.

kill()

kill(): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6730

Beta

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.

Example

tagsQuery.ts

typescript

import { EntityQueryOptions, DimensionLocation } from "@minecraft/server";

function tagsQuery(targetLocation: DimensionLocation) {
  const mobs = ["creeper", "skeleton", "sheep"];

  // create some sample mob data
  for (let i = 0; i < 10; i++) {
    const mobTypeId = mobs[i % mobs.length];
    const entity = targetLocation.dimension.spawnEntity(mobTypeId, targetLocation);
    entity.addTag("mobparty." + mobTypeId);
  }

  const eqo: EntityQueryOptions = {
    tags: ["mobparty.skeleton"],
  };

  for (const entity of targetLocation.dimension.getEntities(eqo)) {
    entity.kill();
  }
}

Inherited from

minecraftserver.Player.kill

lookAtBlock()

lookAtBlock(blockLocation, duration?): void

Defined in: @minecraft/server-gametest/index.d.ts:654

Beta

Parameters

blockLocation

Vector3

duration?

LookDuration

Returns

void

Remarks

Rotates the simulated player's head/body to look at the given block location.

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

Throws

This function can throw errors.

lookAtEntity()

lookAtEntity(entity, duration?): void

Defined in: @minecraft/server-gametest/index.d.ts:664

Beta

Parameters

entity

Entity

duration?

LookDuration

Returns

void

Remarks

Rotates the simulated player's head/body to look at the given entity.

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

Throws

This function can throw errors.

lookAtLocation()

lookAtLocation(location, duration?): void

Defined in: @minecraft/server-gametest/index.d.ts:674

Beta

Parameters

location

Vector3

duration?

LookDuration

Returns

void

Remarks

Rotates the simulated player's head/body to look at the given location.

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

Throws

This function can throw errors.

matches()

matches(options): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6745

Beta

Parameters

options

EntityQueryOptions

The query to perform the match against.

Returns

boolean

Returns true if the entity matches the criteria in the passed in EntityQueryOptions, otherwise it returns false.

Remarks

Matches the entity against the passed in options. Uses the location of the entity for matching if the location is not specified in the passed in EntityQueryOptions.

Throws

Throws if the query options are misconfigured.

Inherited from

minecraftserver.Player.matches

move()

move(westEast, northSouth, speed?): void

Defined in: @minecraft/server-gametest/index.d.ts:684

Beta

Parameters

westEast

number

northSouth

number

speed?

number

Returns

void

Remarks

Orders the simulated player to walk in the given direction relative to the GameTest.

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

Throws

This function can throw errors.

moveRelative()

moveRelative(leftRight, backwardForward, speed?): void

Defined in: @minecraft/server-gametest/index.d.ts:694

Beta

Parameters

leftRight

number

backwardForward

number

speed?

number

Returns

void

Remarks

Orders the simulated player to walk in the given direction relative to the player's current rotation.

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

Throws

This function can throw errors.

moveToBlock()

moveToBlock(blockLocation, options?): void

Defined in: @minecraft/server-gametest/index.d.ts:706

Beta

Parameters

blockLocation

Vector3

options?

MoveToOptions

Returns

void

Remarks

Orders the simulated player to move to the given block location in a straight line. If a move or navigation is already playing, this will override the last move/navigation.

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

Throws

This function can throw errors.

moveToLocation()

moveToLocation(location, options?): void

Defined in: @minecraft/server-gametest/index.d.ts:717

Beta

Parameters

location

Vector3

options?

MoveToOptions

Returns

void

Remarks

Orders the simulated player to move to the given location in a straight line. If a move or navigation is already playing, this will override the last move/navigation.

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

Throws

This function can throw errors.

navigateToBlock()

navigateToBlock(blockLocation, speed?): NavigationResult

Defined in: @minecraft/server-gametest/index.d.ts:731

Beta

Parameters

blockLocation

Vector3

speed?

number

Returns

NavigationResult

Remarks

Orders the simulated player to move to a specific block location using navigation. If a move or navigation is already playing, this will override the last move/walk. Note that if the simulated player gets stuck, that simulated player will stop. The player must be touching the ground in order to start navigation.

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

Throws

This function can throw errors.

navigateToEntity()

navigateToEntity(entity, speed?): NavigationResult

Defined in: @minecraft/server-gametest/index.d.ts:742

Beta

Parameters

entity

Entity

speed?

number

Returns

NavigationResult

Remarks

Will use navigation to follow the selected entity to within a one block radius. If a move or navigation is already playing, this will override the last move/navigation.

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

Throws

This function can throw errors.

navigateToLocation()

navigateToLocation(location, speed?): NavigationResult

Defined in: @minecraft/server-gametest/index.d.ts:756

Beta

Parameters

location

Vector3

speed?

number

Returns

NavigationResult

Remarks

Orders the simulated player to move to a specific location using navigation. If a move or navigation is already playing, this will override the last move/walk. Note that if the simulated player gets stuck, that simulated player will stop. The player must be touching the ground in order to start navigation.

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

Throws

This function can throw errors.

navigateToLocations()

navigateToLocations(locations, speed?): void

Defined in: @minecraft/server-gametest/index.d.ts:771

Beta

Parameters

locations

Vector3[]

A list of locations to use for routing.

speed?

number

Net speed to use for doing the navigation.

Returns

void

Remarks

Use navigation to follow the route provided via the locations parameter. If a move or navigation is already playing, this will override the last move/navigation.

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

Throws

This function can throw errors.

playAnimation()

playAnimation(animationName, options?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6759

Beta

Parameters

animationName

string

The animation identifier. e.g. animation.creeper.swelling

options?

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

minecraftserver.Player.playAnimation

playMusic()

playMusic(trackId, musicOptions?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12551

Beta

Parameters

trackId

string

Identifier of the music track to play.

musicOptions?

MusicOptions

Additional options for the music track.

Returns

void

Remarks

Plays a music track that only this particular player can hear.

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

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.playMusic

playSound()

playSound(soundId, soundOptions?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12590

Beta

Parameters

soundId

string

soundOptions?

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.

Example

playMusicAndSound.ts

typescript

import { world, MusicOptions, WorldSoundOptions, PlayerSoundOptions, DimensionLocation } from "@minecraft/server";

function playMusicAndSound(targetLocation: DimensionLocation) {
  const players = world.getPlayers();

  const musicOptions: MusicOptions = {
    fade: 0.5,
    loop: true,
    volume: 1.0,
  };
  world.playMusic("music.menu", musicOptions);

  const worldSoundOptions: WorldSoundOptions = {
    pitch: 0.5,
    volume: 4.0,
  };
  world.playSound("ambient.weather.thunder", targetLocation, worldSoundOptions);

  const playerSoundOptions: PlayerSoundOptions = {
    pitch: 1.0,
    volume: 1.0,
  };

  players[0].playSound("bucket.fill_water", playerSoundOptions);
}

Inherited from

minecraftserver.Player.playSound

queueMusic()

queueMusic(trackId, musicOptions?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12608

Beta

Parameters

trackId

string

Identifier of the music track to play.

musicOptions?

MusicOptions

Additional options for the music track.

Returns

void

Remarks

Queues an additional music track that only this particular player can hear. If a track is not playing, a music track will play.

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

Throws

An error will be thrown if volume is less than 0.0. An error will be thrown if fade is less than 0.0.

Inherited from

minecraftserver.Player.queueMusic

remove()

remove(): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6770

Beta

Returns

void

Remarks

Immediately removes the entity from the world. The removed entity will not perform a death animation or drop loot upon removal.

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

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.remove

removeEffect()

removeEffect(effectType): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6785

Beta

Parameters

effectType

string | EffectType

The effect identifier.

Returns

boolean

Returns true if the effect has been removed. Returns false if the effect is not found or 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

minecraftserver.Player.removeEffect

removePropertyOverrideForEntity()

removePropertyOverrideForEntity(targetEntity, identifier): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12627

Beta

Parameters

targetEntity

Entity

The Entity whose Entity Property override is being removed.

identifier

string

The Entity Property identifier.

Returns

void

Remarks

For this player, removes the override on an Entity Property. This change is not applied until the next tick and will not apply to other players.

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

Throws

Throws if the entity is invalid. Throws if an invalid identifier is provided. Throws if the provided value type does not match the property type.

Inherited from

minecraftserver.Player.removePropertyOverrideForEntity

removeTag()

removeTag(tag): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6798

Beta

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

minecraftserver.Player.removeTag

resetLevel()

resetLevel(): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12636

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.

Inherited from

minecraftserver.Player.resetLevel

resetProperty()

resetProperty(identifier): string | number | boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6821

Beta

Parameters

identifier

string

The Entity Property identifier.

Returns

string | number | boolean

Returns the default property value. For enum properties, a string is returned. For float and int properties, a number is returned. For undefined properties, undefined is returned.

Remarks

Resets an Entity Property back to its default value, as specified in the Entity's definition. This property change is not applied until the next tick.

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

Throws

Throws if the entity is invalid.

minecraftcommon.EngineError

Error

Inherited from

minecraftserver.Player.resetProperty

respawn()

respawn(): boolean

Defined in: @minecraft/server-gametest/index.d.ts:780

Beta

Returns

boolean

Remarks

Respawns the particular simulated player.

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

Throws

This function can throw errors.

rotateBody()

rotateBody(angleInDegrees): void

Defined in: @minecraft/server-gametest/index.d.ts:790

Beta

Parameters

angleInDegrees

number

Returns

void

Remarks

Causes the simulated player to turn by the provided angle, relative to the player's current rotation.

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

Throws

This function can throw errors.

runCommand()

runCommand(commandString): CommandResult

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6840

Beta

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.

CommandError

InvalidEntityError

Inherited from

minecraftserver.Player.runCommand

runCommandAsync()

runCommandAsync(commandString): Promise<CommandResult>

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6845

Beta

Parameters

commandString

string

Returns

Promise<CommandResult>

Deprecated

This function is deprecated and will be removed in 2.0.0.

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.runCommandAsync

sendMessage()

sendMessage(message): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12726

Beta

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.

InvalidEntityError

RawMessageError

Examples

nestedTranslation.ts

typescript

import { world, DimensionLocation } from "@minecraft/server";

function nestedTranslation(targetLocation: DimensionLocation) {
  // Displays "Apple or Coal"
  const rawMessage = {
    translate: "accessibility.list.or.two",
    with: { rawtext: [{ translate: "item.apple.name" }, { translate: "item.coal.name" }] },
  };
  world.sendMessage(rawMessage);
}

scoreWildcard.ts

typescript

import { world, DimensionLocation } from "@minecraft/server";

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

sendBasicMessage.ts

typescript

import { world, DimensionLocation } from "@minecraft/server";

function sendBasicMessage(targetLocation: DimensionLocation) {
  const players = world.getPlayers();

  players[0].sendMessage("Hello World!");
}

sendPlayerMessages.ts

typescript

import { world, DimensionLocation } from "@minecraft/server";

function sendPlayerMessages(targetLocation: DimensionLocation) {
  for (const player of world.getAllPlayers()) {
    // Displays "First or Second"
    const rawMessage = { translate: "accessibility.list.or.two", with: ["First", "Second"] };
    player.sendMessage(rawMessage);

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

    // Displays "Welcome, Amazing Player 1!"
    player.sendMessage({ translate: "authentication.welcome", with: ["Amazing Player 1"] });

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

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

sendTranslatedMessage.ts

typescript

import { world, DimensionLocation } from "@minecraft/server";

function sendTranslatedMessage(
    targetLocation: DimensionLocation
) {
  const players = world.getPlayers();

  players[0].sendMessage({ translate: "authentication.welcome", with: ["Amazing Player 1"] });
}

Inherited from

minecraftserver.Player.sendMessage

setBodyRotation()

setBodyRotation(angleInDegrees): void

Defined in: @minecraft/server-gametest/index.d.ts:800

Beta

Parameters

angleInDegrees

number

Returns

void

Remarks

Causes the simulated player to turn to face the provided angle, relative to the GameTest.

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

Throws

This function can throw errors.

setDynamicProperty()

setDynamicProperty(identifier, value?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6856

Beta

Parameters

identifier

string

The property identifier.

value?

string | number | boolean | Vector3

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

minecraftserver.Player.setDynamicProperty

setGameMode()

setGameMode(gameMode?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12737

Beta

Parameters

gameMode?

GameMode

Active gamemode.

Returns

void

Remarks

Sets a gamemode override for this player.

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

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.setGameMode

setItem()

setItem(itemStack, slot, selectSlot?): boolean

Defined in: @minecraft/server-gametest/index.d.ts:815

Beta

Parameters

itemStack

ItemStack

Item to set.

slot

number

Slot to place the given item in.

selectSlot?

boolean

Whether to set the selected slot once set.

Returns

boolean

Remarks

Sets a particular item for the simulated player.

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

Throws

This function can throw errors.

setOnFire()

setOnFire(seconds, useEffects?): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6897

Beta

Parameters

seconds

number

Length of time to set the entity on fire.

useEffects?

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. Defaults to: true

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.

Example

setOnFire.ts

typescript

import { system, EntityOnFireComponent, EntityComponentTypes, DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function setOnFire(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const skelly = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Skeleton, targetLocation);

  skelly.setOnFire(20, true);

  system.runTimeout(() => {
    const onfire = skelly.getComponent(EntityComponentTypes.OnFire) as EntityOnFireComponent;
    log(onfire?.onFireTicksRemaining + " fire ticks remaining.");

    skelly.extinguishFire(true);
    log("Never mind. Fire extinguished.");
  }, 20);
}

Inherited from

minecraftserver.Player.setOnFire

setProperty()

setProperty(identifier, value): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6920

Beta

Parameters

identifier

string

The Entity Property identifier.

value

string | number | boolean

The property value. The provided type must be compatible with the type specified in the entity's definition.

Returns

void

Remarks

Sets an Entity Property to the provided value. This property change is not applied until the next tick.

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

Throws

Throws if the entity is invalid. Throws if an invalid identifier is provided. Throws if the provided value type does not match the property type. Throws if the provided value is outside the expected range (int, float properties). Throws if the provided string value does not match the set of accepted enum values (enum properties

Inherited from

minecraftserver.Player.setProperty

setPropertyOverrideForEntity()

setPropertyOverrideForEntity(targetEntity, identifier, value): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12764

Beta

Parameters

targetEntity

Entity

The Entity whose Entity Property is being overriden.

identifier

string

The Entity Property identifier.

value

string | number | boolean

The override value. The provided type must be compatible with the type specified in the entity's definition.

Returns

void

Remarks

For this player, overrides an Entity Property on the target Entity to the provided value. This property must be client synced. This change is not applied until the next tick and will not apply to other players.

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

Throws

Inherited from

minecraftserver.Player.setPropertyOverrideForEntity

setRotation()

setRotation(rotation): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6933

Beta

Parameters

rotation

Vector2

The x and y rotation of the entity (in degrees). 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

minecraftserver.Player.setRotation

setSpawnPoint()

setSpawnPoint(spawnPoint?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12778

Beta

Parameters

spawnPoint?

DimensionLocation

Returns

void

Remarks

Sets the current starting spawn point for this particular player.

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

Throws

This function can throw errors.

Error

LocationOutOfWorldBoundariesError

Inherited from

minecraftserver.Player.setSpawnPoint

spawnParticle()

spawnParticle(effectName, location, molangVariables?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12825

Beta

Parameters

effectName

string

Identifier of the particle to create.

location

Vector3

The location at which to create the particle emitter.

molangVariables?

MolangVariableMap

A set of optional, customizable variables that can be adjusted for this particle.

Returns

void

Remarks

Creates a new particle emitter at a specified location in the world. Only visible to the target player.

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

Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Example

spawnParticle.ts

typescript

import { world, MolangVariableMap, Vector3 } from '@minecraft/server';

world.afterEvents.playerSpawn.subscribe(event => {
    const targetLocation = event.player.location;
    for (let i = 0; i < 100; i++) {
        const molang = new MolangVariableMap();

        molang.setColorRGB('variable.color', {
            red: Math.random(),
            green: Math.random(),
            blue: Math.random()
        });

        const newLocation: Vector3 = {
            x: targetLocation.x + Math.floor(Math.random() * 8) - 4,
            y: targetLocation.y + Math.floor(Math.random() * 8) - 4,
            z: targetLocation.z + Math.floor(Math.random() * 8) - 4,
        };
        event.player.spawnParticle('minecraft:colored_flame_particle', newLocation, molang);
    }
});

Inherited from

minecraftserver.Player.spawnParticle

startBuild()

startBuild(slot?): void

Defined in: @minecraft/server-gametest/index.d.ts:822

Beta

Parameters

slot?

number

Returns

void

Remarks

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

Throws

This function can throw errors.

startItemCooldown()

startItemCooldown(cooldownCategory, tickDuration): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12840

Beta

Parameters

cooldownCategory

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.

Inherited from

minecraftserver.Player.startItemCooldown

stopBreakingBlock()

stopBreakingBlock(): void

Defined in: @minecraft/server-gametest/index.d.ts:831

Beta

Returns

void

Remarks

Stops destroying the block that is currently being hit.

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

Throws

This function can throw errors.

stopBuild()

stopBuild(): void

Defined in: @minecraft/server-gametest/index.d.ts:838

Beta

Returns

void

Remarks

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

Throws

This function can throw errors.

stopFlying()

stopFlying(): void

Defined in: @minecraft/server-gametest/index.d.ts:847

Beta

Returns

void

Remarks

Causes the simulated player to stop flying.

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

Throws

This function can throw errors.

stopGliding()

stopGliding(): void

Defined in: @minecraft/server-gametest/index.d.ts:856

Beta

Returns

void

Remarks

Causes the simulated player to stop gliding.

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

Throws

This function can throw errors.

stopInteracting()

stopInteracting(): void

Defined in: @minecraft/server-gametest/index.d.ts:865

Beta

Returns

void

Remarks

Stops interacting with entities or blocks.

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

Throws

This function can throw errors.

stopMoving()

stopMoving(): void

Defined in: @minecraft/server-gametest/index.d.ts:875

Beta

Returns

void

Remarks

Stops moving/walking/following if the simulated player is moving.

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

Throws

This function can throw errors.

stopMusic()

stopMusic(): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:12850

Beta

Returns

void

Remarks

Stops any music tracks from playing for this particular player.

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

Throws

This function can throw errors.

Inherited from

minecraftserver.Player.stopMusic

stopSwimming()

stopSwimming(): void

Defined in: @minecraft/server-gametest/index.d.ts:884

Beta

Returns

void

Remarks

Causes the simulated player to stop swimming.

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

Throws

This function can throw errors.

stopUsingItem()

stopUsingItem(): ItemStack | undefined

Defined in: @minecraft/server-gametest/index.d.ts:896

Beta

Returns

ItemStack | undefined

Returns the item that was in use. Undefined if no item was in use.

Remarks

Stops using the currently active item.

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

Throws

This function can throw errors.

swim()

swim(): void

Defined in: @minecraft/server-gametest/index.d.ts:905

Beta

Returns

void

Remarks

Causes the simulated player to start swimming.

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

Throws

This function can throw errors.

teleport()

teleport(location, teleportOptions?): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:6988

Beta

Parameters

location

Vector3

New location for the entity.

teleportOptions?

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.

Examples

teleport.ts

typescript

import { system, DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function teleport(targetLocation: DimensionLocation) {
  const cow = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Cow, targetLocation);

  system.runTimeout(() => {
    cow.teleport(
      { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 2 },
      {
        facingLocation: targetLocation,
      }
    );
  }, 20);
}

teleportMovement.ts

typescript

import { system, DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function teleportMovement(targetLocation: DimensionLocation) {
  const pig = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Pig, targetLocation);

  let inc = 1;
  const runId = system.runInterval(() => {
    pig.teleport(
      { x: targetLocation.x + inc / 4, y: targetLocation.y + inc / 4, z: targetLocation.z + inc / 4 },
      {
        facingLocation: targetLocation,
      }
    );

    if (inc > 100) {
      system.clearRun(runId);
    }
    inc++;
  }, 4);
}

Inherited from

minecraftserver.Player.teleport

triggerEvent()

triggerEvent(eventName): void

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:7028

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

If the event is not defined in the definition of the entity, an error will be thrown.

Examples

triggerEvent.ts

typescript

// A function that spawns a creeper and triggers it to explode immediately
import { DimensionLocation } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

function spawnExplodingCreeper(location: DimensionLocation) {
    const creeper = location.dimension.spawnEntity(MinecraftEntityTypes.Creeper, location);

    creeper.triggerEvent('minecraft:start_exploding_forced');
}

triggerEvent.ts

typescript

import { DimensionLocation } from "@minecraft/server";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function triggerEvent(targetLocation: DimensionLocation) {
  const creeper = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Creeper, targetLocation);

  creeper.triggerEvent("minecraft:start_exploding_forced");
}

Inherited from

minecraftserver.Player.triggerEvent

tryTeleport()

tryTeleport(location, teleportOptions?): boolean

Defined in: @minecraft/server-gametest/node_modules/@minecraft/server/index.d.ts:7047

Beta

Parameters

location

Vector3

Location to teleport the entity to.

teleportOptions?

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

minecraftserver.Player.tryTeleport

useItem()

useItem(itemStack): boolean

Defined in: @minecraft/server-gametest/index.d.ts:917

Beta

Parameters

itemStack

ItemStack

Item to use.

Returns

boolean

Remarks

Causes the simulated player to use an item. Does not consume the item. Returns false if the item is on cooldown.

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

Throws

This function can throw errors.

useItemInSlot()

useItemInSlot(slot): boolean

Defined in: @minecraft/server-gametest/index.d.ts:929

Beta

Parameters

slot

number

Index of the inventory slot.

Returns

boolean

Remarks

Causes the simulated player to hold and use an item in their inventory.

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

Throws

This function can throw errors.

useItemInSlotOnBlock()

useItemInSlotOnBlock(slot, blockLocation, direction?, faceLocation?): boolean

Defined in: @minecraft/server-gametest/index.d.ts:949

Beta

Parameters

slot

number

Index of the slot to use.

blockLocation

Vector3

Location to use the item upon.

direction?

Direction

Direction to place the specified item within.

faceLocation?

Vector3

Location relative to the bottom north-west corner of the block where the item is placed.

Returns

boolean

Remarks

Causes the simulated player to use an item in their inventory on a block. The block at the specified block location must be solid. Returns true if the item was used.

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

Throws

This function can throw errors.

useItemOnBlock()

useItemOnBlock(itemStack, blockLocation, direction?, faceLocation?): boolean

Defined in: @minecraft/server-gametest/index.d.ts:974

Beta

Parameters

itemStack

ItemStack

Item to use.

blockLocation

Vector3

Location to use the item upon.

direction?

Direction

Direction to place the specified item within.

faceLocation?

Vector3

Location relative to the bottom north-west corner of the block where the item is placed.

Returns

boolean

Remarks

Causes the simulated player to use an item on a block. The block at the specified block location must be solid. Returns true if the item was used.

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

Throws

This function can throw errors.

Class: SimulatedPlayer ​

Extends ​

Properties ​

camera ​

Remarks ​

Throws ​

Inherited from ​

clientSystemInfo ​

Remarks ​

Throws ​

Inherited from ​

dimension ​

Remarks ​

Throws ​

Inherited from ​

headRotation ​

Remarks ​

Throws ​

id ​

Remarks ​

Inherited from ​

inputInfo ​

Remarks ​

Inherited from ​

inputPermissions ​

Remarks ​

Inherited from ​

isClimbing ​

Remarks ​

Throws ​

Inherited from ​

isEmoting ​

Remarks ​

Throws ​

Inherited from ​

isFalling ​

Remarks ​

Throws ​

Inherited from ​

isFlying ​

Remarks ​

Throws ​

Inherited from ​

isGliding ​

Remarks ​

Throws ​

Inherited from ​

isInWater ​

Remarks ​

Throws ​

Inherited from ​

isJumping ​

Remarks ​

Throws ​

Inherited from ​

isOnGround ​

Remarks ​

Throws ​

Inherited from ​

isSleeping ​

Remarks ​

Throws ​

Inherited from ​

isSneaking ​

Remarks ​

Inherited from ​

isSprinting ​

Remarks ​

Overrides ​

isSwimming ​

Remarks ​

Throws ​

Inherited from ​

level ​

Remarks ​

Throws ​

Inherited from ​

location ​

Remarks ​

Throws ​

Class: SimulatedPlayer

Extends

Properties

camera

Remarks

Throws

Inherited from

clientSystemInfo

Remarks

Throws

Inherited from

dimension

Remarks

Throws

Inherited from

headRotation

Remarks

Throws

id

Remarks

Inherited from

inputInfo

Remarks

Inherited from

inputPermissions

Remarks

Inherited from

isClimbing

Remarks

Throws

Inherited from

isEmoting

Remarks

Throws

Inherited from

isFalling

Remarks

Throws

Inherited from

isFlying

Remarks

Throws

Inherited from

isGliding

Remarks

Throws

Inherited from

isInWater

Remarks

Throws

Inherited from

isJumping

Remarks

Throws

Inherited from

isOnGround

Remarks

Throws

Inherited from

isSleeping

Remarks

Throws

Inherited from

isSneaking

Remarks

Inherited from

isSprinting

Remarks

Overrides

isSwimming

Remarks

Throws

Inherited from

level

Remarks

Throws

Inherited from

location

Remarks

Throws