Class SimulatedPlayer

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 @minecraft/server.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.

Hierarchy (View Summary)

Player
- SimulatedPlayer

Index

Properties

`Readonly`camera

camera: Camera

Remarks

The player's Camera.

Throws

This property can throw when used.

Example: cutscene.js

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

function runCutscene() {
    for (const player of world.getPlayers()) {
        const location = player.location;
        player.camera.setCamera("minecraft:free", {
            location: { x: location.x, y: location.y + 10, z: location.z },
            rotation: { x: 90, y: 0 },
        });
        system.run(() => {
            player.camera.setCamera("minecraft:free", {
                location: player.getHeadLocation(),
                rotation: player.getRotation(),
                easeOptions: {
                    easeTime: 1.0,
                    easeType: EasingType.InCubic,
                },
            });
            system.runTimeout(() => {
                player.camera.clear();
                player.runCommandAsync("/inputpermission @s camera enabled");
                player.runCommandAsync("/inputpermission @s movement enabled");
            }, 20);
        });
        player.runCommandAsync("/inputpermission @s camera disabled");
        player.runCommandAsync("/inputpermission @s movement disabled");
    }
}

runCutscene();

`Readonly`clientSystemInfo

clientSystemInfo: ClientSystemInfo

Remarks

Contains the player's device information.

Throws

This property can throw when used.

Error

`Readonly`dimension

dimension: Dimension

Remarks

Dimension that the entity is currently within.

Throws

This property can throw when used.

Example: spawnItem.js

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

for (const entity of world.getDimension("overworld").getEntities()) {
    entity.dimension.spawnItem(
        new ItemStack("minecraft:diamond_sword"),
        entity.location
    );
}

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

Example: trapEntity.js

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

const id = "-0123456789101"; // entity.id
const entity = world.getEntity(id);
entity.runCommandAsync("say hello");

`Readonly` `Beta`inputInfo

inputInfo: InputInfo

Remarks

Contains the player's input information.

`Readonly`inputPermissions

inputPermissions: PlayerInputPermissions

Remarks

Input permissions of the player.

`Readonly`isClimbing

isClimbing: boolean

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.

Example: debug.js

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

system.runInterval(() => {
    for (const entity of world.getDimension("overworld").getEntities()) {
        // Force entity to not sneak
        entity.isSneaking = false;
    }
});

`Readonly`isEmoting

isEmoting: boolean

Remarks

If true, the player is currently emoting.

Throws

This property can throw when used.

`Readonly`isFalling

isFalling: boolean

Remarks

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

Throws

This property can throw when used.

Example: debug.js

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

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        player.sendMessage(`isClimbing - ${player.isClimbing}`);
    }
});

`Readonly`isFlying

isFlying: boolean

Remarks

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

Throws

This property can throw when used.

Example: isPlayerFlying.js

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

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        player.sendMessage(`player is flying: ${player.isFlying}`);
    }
});

`Readonly`isGliding

isGliding: boolean

Remarks

Whether the player is gliding with Elytra.

Throws

This property can throw when used.

Example: isPlayerGliding.js

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

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        player.sendMessage(
            `player is gliding with Elytra: ${player.isGliding}`
        );
    }
});

`Readonly`isInWater

isInWater: boolean

Remarks

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

Throws

This property can throw when used.

Example: playerInWater.js

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

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        player.sendMessage(`player in water: ${player.isInWater}`);
    }
});

`Readonly`isJumping

isJumping: boolean

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.

Example: isPlayerJumping.js

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

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        player.sendMessage(`player is jumping: ${player.isJumping}`);
    }
});

`Readonly`isOnGround

isOnGround: boolean

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.

Example: playerOnGround.js

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

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        player.sendMessage(`player on ground: ${player.isOnGround}`);
    }
});

`Readonly`isSleeping

isSleeping: boolean

Remarks

If true, the entity is currently sleeping.

Throws

This property can throw when used.

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.

Example: alwaysSneak.ts

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

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        player.isSneaking = true;
    }
});

Example: playerIsSneaking.ts

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

function spawnConfetti(location: DimensionLocation) {
    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: location.x + Math.floor(Math.random() * 8) - 4,
            y: location.y + Math.floor(Math.random() * 8) - 4,
            z: location.z + Math.floor(Math.random() * 8) - 4,
        };
        location.dimension.spawnParticle(
            "minecraft:colored_flame_particle",
            newLocation,
            molang
        );
    }
}

system.runInterval(() => {
    for (const player of world.getPlayers()) {
        if (player.isSneaking) {
            spawnConfetti({
                dimension: player.dimension,
                x: player.location.x,
                y: player.location.y,
                z: player.location.z,
            });
            player.sendMessage("player is sneaking");
        }
    }
});

`Readonly`isSprinting

isSprinting: boolean

Remarks

Whether the entity is sprinting. For example, a player using the sprint action, an ocelot running away or a pig boosting with Carrot on a Stick.

Throws

This property can throw when used.

`Readonly`isSwimming

isSwimming: boolean

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.

`Readonly`level

level: number

Remarks

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

Throws

This property can throw when used.

Example: awfulCountdown.ts

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

function countdownFromTen(player: Player) {
    player.addLevels(-10000);
    player.addLevels(11);
    const id = system.runInterval(() => {
        player.addExperience(
            Math.round(-player.totalXpNeededForNextLevel / 10)
        );
        if (player.getTotalXp() === 0) {
            system.clearRun(id);
        }
        if (player.xpEarnedAtCurrentLevel == 0) {
            player.addLevels(-1);
            player.addExperience(player.totalXpNeededForNextLevel - 1);
        }
    }, 2);
}
for (const player of world.getPlayers()) {
    countdownFromTen(player);
}

Example: showProgress.ts

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

for (const player of world.getAllPlayers()) {
    player.onScreenDisplay.setActionBar(
        `Level: ${player.level}, xp at current level: ${player.xpEarnedAtCurrentLevel} / ${player.totalXpNeededForNextLevel}`
    );
}

`Readonly`location

location: Vector3

Remarks

Current location of the entity.

Throws

This property can throw when used.

Example: showLocation.js

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

world.afterEvents.buttonPush.subscribe((event) => {
    if (event.source.typeId === "minecraft:player") {
        event.source.kill();
    }
});

`Readonly`name

name: string

Remarks

Name of the player.

Throws

This property can throw when used.

Example: welcomeMessage.ts

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

world.afterEvents.playerSpawn.subscribe((event) => {
    world.sendMessage("Welcome to the server, " + event.player.name + "!");
});

nameTag

nameTag: string

Remarks

Given name of the entity.

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

Example: dinnerboneEveryMob.ts

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

system.afterEvents.scriptEventReceive.subscribe(({ message }) => {
    if (message === "dinnerbone:true") {
        for (const entity of world.getDimension("overworld").getEntities()) {
            entity.nameTag = "Dinnerbone";
        }
    }
});

`Readonly`onScreenDisplay

onScreenDisplay: ScreenDisplay

Remarks

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

Throws

This property can throw when used.

Example: setActionBar.ts

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

for (const player of world.getAllPlayers()) {
    player.onScreenDisplay.setActionBar("Hello World");
}

Example: showHotbarOnly.ts

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

for (const player of world.getAllPlayers()) {
    player.onScreenDisplay.hideAllExcept([HudElement.Hotbar]);
}

Example: subtitleOnly.ts

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

for (const player of world.getAllPlayers()) {
    player.onScreenDisplay.setTitle("  "); // spaces needed
    player.onScreenDisplay.updateSubtitle("Insert Subtitle");
}

Example: welcome.ts

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

for (const player of world.getAllPlayers()) {
    player.onScreenDisplay.setTitle("Hello World");
    player.onScreenDisplay.updateSubtitle("Welcome to the server!");
}

`Optional` `Readonly`scoreboardIdentity

scoreboardIdentity?: ScoreboardIdentity

Remarks

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

selectedSlotIndex

selectedSlotIndex: number

Remarks

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

Example: saySelectedItem.ts

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

for (const player of world.getPlayers()) {
    const inventory = player.getComponent("inventory");
    const selectedItem = inventory.container.getItem(player.selectedSlotIndex);
    player.sendMessage("Selected Item: " + selectedItem.typeId);
}

`Optional` `Readonly` `Beta`target

target?: Entity

Remarks

Retrieves or sets an entity that is used as the target of AI-related behaviors, like attacking. If the entity currently has no target returns undefined.

Throws

This property can throw when used.

`Readonly`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

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

Example: showLocation.js

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

// This event triggers when world is loaded
system.runInterval(() => {
    const entity = world.getDimension("overworld").getEntities()[0];
    // Finally, show that location as title
    entity.runCommandAsync(
        `title @a actionbar X: ${Math.floor(
            entity.location.x
        )} | Y: ${Math.floor(entity.location.y)} | Z: ${Math.floor(
            entity.location.z
        )}`
    );
});

`Readonly`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,
): Effect

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 Effect

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: spawnPoisonedVillager.ts

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

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

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

Example: quickFoxLazyDog.ts

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);
}

addExperience

addExperience(amount: number): number
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.
Example: addXpToPlayer.ts
```
import { Player, world } from "@minecraft/server";

// Command equivalent to /xp player 100
function addExperience(player: Player) {
    const xpAdded = player.addExperience(100);
    console.log(`Player ${player.name} now has ${xpAdded} experience points.`);
}

for (const player of world.getPlayers()) {
    addExperience(player);
}
```
Inherited from Player.addExperience

addLevels

addLevels(amount: number): number
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.
Example: addLevels.ts
```
import { Player, world } from "@minecraft/server";

// Command equivalent to /xp player 5L
function addLevels(player: Player) {
    const levels = player.addLevels(5);
    console.log(`Player ${player.name} now has ${levels} levels.`);
}
```
Inherited from Player.addLevels

addTag

addTag(tag: string): boolean

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

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();
  }
}

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.

Example: applyDamageThenHeal.ts

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);
}

Example: applyWither.js

import { world, EntityDamageCause } from "@minecraft/server";
const player = world.getAllPlayers()[0];
player.applyDamage(1000, {
    cause: EntityDamageCause.wither,
});

Example: damageEntity.js

import { world } from "@minecraft/server";
world.afterEvents.itemUse.subscribe((event) => {
    const player = event.source;
    const damageApplied = player.applyDamage(10);
    console.log(`Damage applied: ${damageApplied}`);
});

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.

Example: applyImpulse.ts

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 });
}

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.

Example: bounceSkeletons.ts

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);
  }
}

clearDynamicProperties

clearDynamicProperties(): void
Returns void
Remarks
Clears all dynamic properties that have been set on this entity.

Throws
This function can throw errors.
Example: resetStats.js
```
import { world } from "@minecraft/server";

for (const entity of world.getDimension("overworld").getEntities()) {
    entity.clearDynamicProperties();
}
```
Inherited from Player.clearDynamicProperties

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.

Example: applyImpulse.ts

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 });
}

eatItem

eatItem(itemStack: ItemStack): void
Beta
Parameters
- itemStack: ItemStack
  The item to eat.
Returns void
Remarks
Eats an item, providing the item's hunger and saturation effects to the player. Can only be used on food items.

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

Throws
Throws if the item is not a food item.

Inherited from Player.eatItem

extinguishFire

extinguishFire(useEffects?: boolean): boolean

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.

Example: setOnFire.ts

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);
}

getBlockFromViewDirection

getBlockFromViewDirection(options?: BlockRaycastOptions): BlockRaycastHit

Parameters

Optionaloptions: BlockRaycastOptions
Additional configuration options for the ray cast.

Returns BlockRaycastHit

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.

Example: facingBlock.js

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

for (const entity of world.getDimension("overworld").getEntities()) {
    const blockHit = entity.getBlockFromViewDirection();

    if (blockHit) {
        console.log("Block Hit:");
        console.log("Block:", blockHit.block);
        console.log("Face:", blockHit.face);
        console.log("Face Location:", JSON.stringify(blockHit.faceLocation));
    } else {
        console.log("No block in view direction.");
    }
}

Example: setBedrock.js

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

const entity = world
    .getDimension("overworld")
    .spawnEntity("minecraft:fox", { x: 0, y: 0, z: 0 });
const blockHit = entity.getBlockFromViewDirection();

if (blockHit) {
    blockHit.block.setPermutation(
        BlockPermutation.resolve("minecraft:bedrock")
    );
} else {
    console.log("No block in view direction.");
}

getComponent

getComponent<T extends keyof EntityComponentTypeMap>(
componentId: T,
): EntityComponentTypeMap[T]

Type Parameters

T extends keyof EntityComponentTypeMap

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 EntityComponentTypeMap[T]

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

Remarks

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

Example: entityHealth.js

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

for (const player of world.getPlayers()) {
    const health = player.getComponent("health");
    player.sendMessage(
        "Your health is " + health.currentValue + "/" + health.effectiveMax
    );
    health.setCurrentValue(15); // set player to 15 hp
    health.resetToMaxValue(); // reset player to max hp
}

Example: entityInventory.js

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

world.afterEvents.buttonPush.subscribe((event) => {
    const entity = event.source;
    entity
        .getComponent("inventory")
        .container.addItem(new ItemStack("minecraft:dirt", 1));
});

Example: entityItem.js

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

const itemEntities = world
    .getDimension("overworld")
    .getEntities({ type: "minecraft:item" });
for (const itemEntity of itemEntities) {
    const item = itemEntity.getComponent("item");
    item.itemStack.keepOnDeath = true;
}

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.

Example: getComponents.js

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

for (const entity of world.getDimension("overworld").getEntities()) {
    const components = entity.getComponents();
    console.log(
        `Number of components: ${components.length}: ${components.map(
            (component) => component.typeId
        )}`
    );
}

getDynamicProperty

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

Parameters

identifier: string
The property identifier.

Returns string | number | boolean | Vector3

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.

Example: entityRespawn.ts

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

world.afterEvents.entitySpawn.subscribe((event) => {
    event.entity.setDynamicProperty("spawn_location", event.entity.location); // set location spawn
});

world.beforeEvents.entityRemove.subscribe((event) => {
    const location = event.removedEntity.getDynamicProperty(
        "spawn_location"
    ) as Vector3; // get location spawn
    const dimension = event.removedEntity.dimension;
    system.run(() => {
        dimension.spawnEntity(event.removedEntity.typeId, location);
    });
});

getDynamicPropertyIds

getDynamicPropertyIds(): string[]

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.

Example: displayEntries.ts

import { Player, system } from "@minecraft/server";

system.afterEvents.scriptEventReceive.subscribe((event) => {
    // Type /scriptevent bp:entries to see this message
    if (event.id === "bp:entries" && event.sourceEntity instanceof Player) {
        event.sourceEntity.sendMessage(
            "Here's your dynamic properties entries:"
        );

        // Display all dynamic properties
        for (const id of event.sourceEntity.getDynamicPropertyIds()) {
            event.sourceEntity.sendMessage(
                `- ${id}: ${event.sourceEntity.getDynamicProperty(id)}`
            );
        }
    }
});

getDynamicPropertyTotalByteCount

getDynamicPropertyTotalByteCount(): number

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.

Example: displayByteCount.ts

import { Player, system } from "@minecraft/server";

system.afterEvents.scriptEventReceive.subscribe((event) => {
    // Type /scriptevent dp:size to see this message
    if (event.id === "dp:size" && event.sourceEntity instanceof Player) {
        // Returns the total size, in bytes, of all the dynamic properties that are currently stored for this entity.
        const byteCount = event.sourceEntity.getDynamicPropertyTotalByteCount();

        // Send the byte count to the player
        event.sourceEntity.sendMessage(
            `Dynamic Properties Byte Count: ${byteCount}`
        );
    }
});

getEffect

getEffect(effectType: string | EffectType): Effect
Parameters
- effectType: string | EffectType
  The effect identifier.
Returns 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.
Example: getEntityEffectInfo.js
```
import { world } from "@minecraft/server";

const entities = world.getDimension("overworld").getEntities();
for (const entity of entities) {
    entity.getEffects().forEach((effect) => {
        console.log(effect.typeId, effect.amplifier, effect.duration);
    });
}
```
Inherited from Player.getEffect

getEffects

getEffects(): Effect[]

Returns Effect[]

List of effects.

Remarks

Returns a set of effects applied to this entity.

Throws

This function can throw errors.

Example: getEntityEffectInfo.js

import { world } from "@minecraft/server";
for (const entity of world.getDimension("overworld").getEntities()) {
    const effect = entity.getEffect("invisibility");
    effect.amplifier;
    effect.duration;
}

getEntitiesFromViewDirection

getEntitiesFromViewDirection(options?: EntityRaycastOptions): EntityRaycastHit[]

Parameters

Optionaloptions: 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.

Example: entityView.ts

import type { EntityRaycastOptions } from "@minecraft/server";
import { world } from "@minecraft/server";

// Optional: Configure ray cast options
const raycastOptions: EntityRaycastOptions = {
    maxDistance: 10, // Set your desired maximum distance
};

// Perform the ray cast

for (const entity of world.getDimension("overworld").getEntities()) {
    const entitiesInView = entity.getEntitiesFromViewDirection(raycastOptions);

    // Log the results
    entitiesInView.forEach((hit) => {
        console.log(`Entity hit at distance ${hit.distance} blocks.`);
        console.log("Entity details:", hit.entity); // You can access properties/methods of the hit entity
    });
}

getGameMode

getGameMode(): GameMode

Returns GameMode

Remarks

Retrieves the active gamemode for this player, if specified.

Throws

This function can throw errors.

Example: displayGameMode.js

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

for (const player of world.getAllPlayers()) {
    const gameMode = player.getGameMode();
    player.sendMessage(`Your game mode is ${gameMode}`);
}

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.

Example: freezePlayerCamera.ts

import { Player } from "@minecraft/server";

function freezePlayerCamera(player: Player) {
    player.camera.setCamera("minecraft:free", {
        location: player.getHeadLocation(),
        rotation: player.getRotation(),
    });
}

getItemCooldown

getItemCooldown(cooldownCategory: string): number
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.
Example: getEquipmentCooldown.js
```
import { world } from "@minecraft/server";

const player = world.getAllPlayers()[0];
const cooldown = player.getItemCooldown("equipment");
console.log(`Cooldown for the equipment category: ${cooldown} seconds.`);
```
Inherited from Player.getItemCooldown

getProperty

getProperty(identifier: string): string | number | boolean
Parameters
- identifier: string
  The entity Property identifier.
Returns string | number | boolean
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.
Example: getRotationOffset.js
```
import { world } from "@minecraft/server";

const entity = world
    .getDimension("overworld")
    .getEntities({ type: "create:dummy" })[0];
entity.setProperty("create:rotation_offset", 1);
console.warn(entity.getProperty("create:rotation_offset"));
```
Inherited from Player.getProperty

getRotation

getRotation(): Vector2

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.

Example: getRotation.js

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

world.beforeEvents.chatSend.subscribe((event) => {
    const message = event.message;
    const player = event.sender;
    if (message === "rotation get") {
        event.cancel = true;
        const rotation = player.getRotation();
        player.sendMessage(`Spawn point location: ${rotation.x} ${rotation.y}`);
    }
});

getSpawnPoint

getSpawnPoint(): DimensionLocation

Returns DimensionLocation

Remarks

Gets the current spawn point of the player.

Throws

This function can throw errors.

Example: getSpawnPoint.js

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

world.beforeEvents.chatSend.subscribe((event) => {
    const message = event.message;
    const player = event.sender;
    if (message === "spawnpoint get") {
        event.cancel = true;
        const spawnPoint = player.getSpawnPoint();
        if (spawnPoint) {
            player.sendMessage(
                `Spawn point location: ${spawnPoint.x} ${spawnPoint.y} ${spawnPoint.z} at ${spawnPoint.dimension.id}`
            );
        } else {
            player.sendMessage(`No spawn point set.`);
        }
    }
});

getTags

getTags(): string[]

Returns string[]

An array containing all tags as strings.

Remarks

Returns all tags associated with the entity.

Throws

This function can throw errors.

Example: jaylyTag.js

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

for (const entity of world.getDimension("overworld").getEntities()) {
    const tags = entity.getTags();
    const jaylyTag = tags.find((tag) => tag.startsWith("jayly:"));
    if (jaylyTag) {
        world.sendMessage(`${entity.id}: ${jaylyTag}`);
    }
}

getTotalXp

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

Throws
This function can throw errors.

Inherited from Player.getTotalXp

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.

Example: getFireworkVelocity.ts

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);
}

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 Player.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.
Example: hasComponents.js
```
import { world } from "@minecraft/server";

const entity = world
    .getDimension("overworld")
    .getEntities({ type: "minecraft:villager" })[0];
entity.hasComponent("tameable");
entity.hasComponent("inventory");
entity.hasComponent("addrider");
entity.hasComponent("is_tamed");
```
Inherited from Player.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 Player.hasTag

isOp

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

Throws
This function can throw errors.

Inherited from Player.isOp

isValid

isValid(): boolean

Returns boolean

Whether the entity is valid.

Remarks

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

Example: tracky.ts

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

const zombie = world
    .getDimension("overworld")
    .spawnEntity("minecraft:zombie", world.getDefaultSpawnLocation());

const id = system.runInterval(() => {
    if (!zombie.isValid()) {
        system.clearRun(id);
        return;
    }
    const location = zombie.location;
    for (const player of world.getPlayers()) {
        player.sendMessage(
            `Zombie location: (${location.x.toFixed(2)}, ${location.y.toFixed(
                2
            )}, ${location.z.toFixed(2)})`
        );
    }
});

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.

Example: tagsQuery.ts

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();
  }
}

lookAt

lookAt(targetLocation: Vector3): void
Beta
Parameters
- targetLocation: Vector3
  The target location that this entity should face/look towards.
Returns void
Remarks
Sets the rotation of the entity to face a target location. Both pitch and yaw will be set, if applicable, such as for mobs where the pitch controls the head tilt and the yaw controls the body rotation.

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

Throws
This function can throw errors.

Inherited from Player.lookAt

matches

matches(options: EntityQueryOptions): boolean
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.
Example: isSpectator.js
```
import { GameMode, system, world } from "@minecraft/server";
system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        const isSpectating = player.matches({ gameMode: GameMode.spectator });
        if (isSpectating) {
            player.onScreenDisplay.setActionBar("You are spectating");
        }
    }
});
```
Inherited from Player.matches

playAnimation

playAnimation(animationName: string, options?: PlayAnimationOptions): void
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 Player.playAnimation

playMusic

playMusic(trackId: string, musicOptions?: MusicOptions): void
Parameters
- trackId: string
  Identifier of the music track to play.
- OptionalmusicOptions: 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 Player.playMusic

playSound

playSound(soundId: string, soundOptions?: PlayerSoundOptions): void

Parameters

soundId: string
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.

Example: playMusicAndSound.ts

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);
}

Example: playCreatorMusicBox.ts

import { Player } from "@minecraft/server";

// Scripting code for `playsound
function playCreatorMusicBoxRecord(player: Player) {
    player.playSound("record.creator_music_box", { location: player.location });
}

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.

Inherited from Player.postClientMessage

queueMusic

queueMusic(trackId: string, musicOptions?: MusicOptions): void

Parameters

trackId: string
Identifier of the music track to play.
OptionalmusicOptions: 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.

Example: queueAllMusic.ts

import { Player } from "@minecraft/server";

// Surely someone enjoy minecraft ambient music
const allMusic = [
    "music.overworld.bamboo_jungle",
    "music.overworld.bamboo_jungle",
    "music.game.basalt_deltas",
    "music.game_and_wild_equal_chance",
    "music.game_and_wild_equal_chance",
    "music.game_and_wild_favor_game",
    "music.overworld.cherry_grove",
    "music.game.creative",
    "music.game.credits",
    "music.game.crimson_forest",
    "music.overworld.deep_dark",
    "music.overworld.desert",
    "music.overworld.desert",
    "music.overworld.desert",
    "music.overworld.dripstone_caves",
    "music.game.end",
    "music.game.endboss",
    "music.overworld.flower_forest",
    "music.game_and_wild_equal_chance",
    "music.game.frozen_peaks",
    "music.game",
    "music.overworld.grove",
    "music.game.nether_wastes",
    "music.overworld.jagged_peaks",
    "music.overworld.jungle",
    "music.overworld.jungle_edge",
    "music.overworld.jungle",
    "music.overworld.jungle",
    "music.game_and_wild_equal_chance",
    "music.overworld.lush_caves",
    "music.game.swamp_music",
    "music.game.meadow",
    "music.game_and_wild_favor_game",
    "music.menu",
    "music.overworld.mesa",
    "music.overworld.mesa",
    "music.overworld.mesa",
    "music.game.nether",
    "music.game_and_wild_favor_game",
    "music.game_and_wild_favor_game",
    "music.game_and_wild_equal_chance",
    "music.game_and_wild_equal_chance",
    "music.overworld.snowy_slopes",
    "music.game.soulsand_valley",
    "music.overworld.stony_peaks",
    "music.game.swamp_music",
    "music.game.swamp_music",
    "music.game.water",
];

function queueAllMusic(player: Player) {
    for (const musicTrackId of allMusic) {
        player.queueMusic(musicTrackId, { fade: 1.0 });
    }
}

remove

remove(): void

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.

Example: removeAllEntities.ts

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

// Note: You cannot despawn players via entity.remove()
const entities = world
    .getDimension("overworld")
    .getEntities({ excludeTypes: ["minecraft:player"] });

for (const entity of entities) {
    entity.remove();
}

removeEffect

removeEffect(effectType: string | EffectType): boolean
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 Player.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.
Example: removeAdminTag.ts
```
import { world } from "@minecraft/server";

for (const player of world.getAllPlayers()) {
    player.removeTag("admin");
}
```
Inherited from Player.removeTag

resetLevel

resetLevel(): void
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.
Example: resetEveryoneLevel.ts
```
import { world } from "@minecraft/server";

for (const player of world.getAllPlayers()) {
    player.resetLevel();
}
```
Inherited from Player.resetLevel

resetProperty

resetProperty(identifier: string): string | number | boolean
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 Player.resetProperty

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.

CommandError

Error
Example: sayCommand.js
```
import { world } from "@minecraft/server";

world.afterEvents.entityDie.subscribe((event) => {
    event.deadEntity.runCommand("say I am dead!");
});
```
Inherited from Player.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.
Example: sayCommand.js
```
import { world } from "@minecraft/server";

world.beforeEvents.explosion.subscribe((event) => {
    event.source?.runCommandAsync("say I exploded!");
});
```
Inherited from Player.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

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);
}

Example: scoreWildcard.ts

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);
}

Example: sendBasicMessage.ts

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

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

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

Example: sendPlayerMessages.ts

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);
  }
}

Example: sendTranslatedMessage.ts

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

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

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

setDynamicProperty

setDynamicProperty(
identifier: string,
value?: string | number | boolean | Vector3,
): void

Parameters

identifier: string
The property identifier.
Optionalvalue: 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.

Example: entityRespawn.ts

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

world.afterEvents.entitySpawn.subscribe((event) => {
    event.entity.setDynamicProperty("spawn_location", event.entity.location); // set location spawn
});

world.beforeEvents.entityRemove.subscribe((event) => {
    const location = event.removedEntity.getDynamicProperty(
        "spawn_location"
    ) as Vector3; // get location spawn
    const dimension = event.removedEntity.dimension;
    system.run(() => {
        dimension.spawnEntity(event.removedEntity.typeId, location);
    });
});

setGameMode

setGameMode(gameMode?: GameMode): void
Parameters
- OptionalgameMode: 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.
Example: setCreativeMode.js
```
import { GameMode, world } from "@minecraft/server";

for (const player of world.getAllPlayers()) {
    player.setGameMode(GameMode.creative);
}
```
Inherited from Player.setGameMode

setOnFire

setOnFire(seconds: number, useEffects?: boolean): boolean

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.

Example: setOnFire.ts

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);
}

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.

Inherited from Player.setOp

setProperty

setProperty(identifier: string, value: string | number | boolean): void
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
Example: getRotationOffset.js
```
import { world } from "@minecraft/server";

const tileEntity = world
    .getDimension("overworld")
    .getEntities({ type: "create:dummy" })[0];
tileEntity.setProperty("create:rotation_offset", 1);
console.warn(tileEntity.getProperty("create:rotation_offset"));
```
Inherited from Player.setProperty

setRotation

setRotation(rotation: Vector2): void
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 Player.setRotation

setSpawnPoint

setSpawnPoint(spawnPoint?: DimensionLocation): void
Parameters
- OptionalspawnPoint: 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 Player.setSpawnPoint

spawnParticle

spawnParticle(
    effectName: string,
    location: Vector3,
    molangVariables?: MolangVariableMap,
): void

Beta

Parameters

effectName: string
Identifier of the particle to create.
location: Vector3
The location at which to create the particle emitter.
OptionalmolangVariables: 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

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);
    }
});

startItemCooldown

startItemCooldown(cooldownCategory: string, tickDuration: number): void
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 Player.startItemCooldown

stopMusic

stopMusic(): void
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 Player.stopMusic

teleport

teleport(location: Vector3, teleportOptions?: TeleportOptions): void

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.

Example: teleport.ts

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);
}

Example: teleportMovement.ts

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);
}

Example: teleport.js

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

system.afterEvents.scriptEventReceive.subscribe(({ sourceEntity, message }) => {
    if (!sourceEntity) return;

    if (message === "tp:nether") {
        sourceEntity.teleport(
            { x: 0, y: 0, z: 0 },
            { dimension: world.getDimension("nether") }
        );
    }
});

Example: teleportFacing.js

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

system.afterEvents.scriptEventReceive.subscribe(({ sourceEntity, message }) => {
    if (!sourceEntity) return;

    if (message === "tp:nether") {
        sourceEntity.teleport(
            { x: 0, y: 0, z: 0 },
            {
                dimension: world.getDimension("nether"),
                facingLocation: { x: 100, y: 100, z: 100 },
            }
        );
    }
});

triggerEvent

triggerEvent(eventName: string): void

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.

Example: triggerEvent.ts

// 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');
}

Example: triggerEvent.ts

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");
}

tryTeleport

tryTeleport(location: Vector3, teleportOptions?: TeleportOptions): boolean
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 Player.tryTeleport

Class SimulatedPlayer

Hierarchy (View Summary)

Index

Properties

Methods

Properties

Readonlycamera

Remarks

Throws

Example: cutscene.js

ReadonlyclientSystemInfo

Remarks

Throws

Readonlydimension

Remarks

Throws

Example: spawnItem.js

Readonlyid

Remarks

Example: trapEntity.js

Readonly BetainputInfo

Remarks

ReadonlyinputPermissions

Remarks

ReadonlyisClimbing

Remarks

Throws

Example: debug.js

ReadonlyisEmoting

Remarks

Throws

ReadonlyisFalling

Remarks

Throws

Example: debug.js

ReadonlyisFlying

Remarks

Throws

Example: isPlayerFlying.js

ReadonlyisGliding

Remarks

Throws

Example: isPlayerGliding.js

ReadonlyisInWater

Remarks

Throws

Example: playerInWater.js

ReadonlyisJumping

Remarks

Throws

Example: isPlayerJumping.js

ReadonlyisOnGround

Remarks

Throws

Example: playerOnGround.js

ReadonlyisSleeping

Remarks

Throws

isSneaking

Remarks

Example: alwaysSneak.ts

Example: playerIsSneaking.ts

ReadonlyisSprinting

Remarks

Throws

ReadonlyisSwimming

Remarks

Throws

Readonlylevel

Remarks

Throws

Example: awfulCountdown.ts

Example: showProgress.ts

Readonlylocation

Remarks

Throws

Example: showLocation.js

Readonlyname

Remarks

Throws

`Readonly`camera

`Readonly`clientSystemInfo

`Readonly`dimension

`Readonly`id

`Readonly` `Beta`inputInfo

`Readonly`inputPermissions

`Readonly`isClimbing

`Readonly`isEmoting

`Readonly`isFalling

`Readonly`isFlying

`Readonly`isGliding

`Readonly`isInWater

`Readonly`isJumping

`Readonly`isOnGround

`Readonly`isSleeping

`Readonly`isSprinting

`Readonly`isSwimming

`Readonly`level

`Readonly`location

`Readonly`name

`Readonly`onScreenDisplay

`Optional` `Readonly`scoreboardIdentity

`Optional` `Readonly` `Beta`target

`Readonly`totalXpNeededForNextLevel

`Readonly`typeId

`Readonly`xpEarnedAtCurrentLevel