Represents the state of an entity (a mob, the player, or other moving objects like minecarts) in the world.

Hierarchy

Constructors

Properties

dimension: Dimension

Remarks

Dimension that the entity is currently within.

Throws

This property can throw when used.

Example

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

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

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

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

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

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

isSleeping: boolean

Remarks

If true, the entity is currently sleeping.

Throws

This property can throw when used.

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

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.

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.

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

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

scoreboardIdentity?: ScoreboardIdentity

Remarks

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

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

Methods

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

    • Optional options: EntityEffectOptions

      Additional options for the effect.

      Optional

    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

    poisonVillager.ts

    // Spawns a villager and gives it the poison effect
    import {
    DimensionLocation,
    } from '@minecraft/server';
    import { MinecraftEffectTypes } from '@minecraft/vanilla-data';

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

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

    Example

    quickFoxLazyDog.ts

    // Spawns a fox over a dog
    import { DimensionLocation } from '@minecraft/server';
    import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

    function spawnAdultHorse(location: DimensionLocation) {
    // Create fox (our quick brown fox)
    const fox = location.dimension.spawnEntity(MinecraftEntityTypes.Fox, {
    x: location.x,
    y: location.y + 2,
    z: location.z,
    });

    fox.addEffect('speed', 10, {
    amplifier: 2,
    });

    // Create wolf (our lazy dog)
    const wolf = location.dimension.spawnEntity(MinecraftEntityTypes.Wolf, location);
    wolf.addEffect('slowness', 10, {
    amplifier: 2,
    });
    wolf.isSneaking = true;
    }

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

  • Parameters

    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

    // A function that applies damage and then heals the entity
    import { Entity, EntityComponentTypes, system, world } from '@minecraft/server';

    function applyDamageAndHeal(entity: Entity) {
    entity.applyDamage(19); // Many mobs have max damage of 20 so this is a near-death mob

    system.runTimeout(() => {
    const health = entity.getComponent(EntityComponentTypes.Health);
    if (health) {
    world.sendMessage(`Entity health before heal: ${health.currentValue}`);

    health.resetToMaxValue();

    world.sendMessage(`Entity after before heal: ${health.currentValue}`);
    } else {
    console.warn('Entity does not have health component');
    }
    }, 40); // Run in a few seconds (40 ticks)
    }

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

  • Parameters

    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

    yeetEntity.ts

    // A function that throws entities up in the air
    import { Entity } from '@minecraft/server';

    function yeetEntity(entity: Entity) {

    // Zero out the entity's velocity before applying impulse
    entity.clearVelocity();

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

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

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

  • 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

    yeetEntity.ts

    // A function that throws entities up in the air
    import { Entity } from '@minecraft/server';

    function yeetEntity(entity: Entity) {

    // Zero out the entity's velocity before applying impulse
    entity.clearVelocity();

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

  • Parameters

    • Optional useEffects: boolean

      Whether to show any visual effects connected to the extinguishing.

      Optional

    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

    setEntityOnFire.ts

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

    function setAblaze(entity: Entity) {
    entity.setOnFire(20, true);

    system.runTimeout(() => {
    const onfire = entity.getComponent(EntityComponentTypes.OnFire);
    if (onfire) {
    world.sendMessage(`${onfire.onFireTicksRemaining} fire ticks remaining, extinguishing the entity.`);
    }
    // This will extinguish the entity
    entity.extinguishFire(true);
    }, 30); // Run in 30 ticks or ~1.5 seconds

    }

  • Parameters

    • Optional options: BlockRaycastOptions

      Additional configuration options for the ray cast.

      Optional

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

  • Parameters

    • componentId: string

      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 EntityComponent

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

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

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

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

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

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

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

  • Parameters

    • Optional options: EntityRaycastOptions

      Additional configuration options for the ray cast.

      Optional

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

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

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

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

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

  • 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

    // A function that spawns fireworks and logs their velocity after 5 ticks
    import { DimensionLocation, system, world } from '@minecraft/server';
    import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

    function spawnFireworks(location: DimensionLocation) {
    const fireworkRocket = location.dimension.spawnEntity(MinecraftEntityTypes.FireworksRocket, location);

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

    world.sendMessage(`Velocity of firework is: ${velocity.x}, ${velocity.y}, ${velocity.z}`);
    }, 5);
    }

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

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

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

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

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

  • Parameters

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

  • Parameters

    • animationName: string

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

    • Optional options: PlayAnimationOptions

      Additional options to control the playback and transitions of the animation.

      Optional

    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.

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

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

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

  • 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

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

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

  • Parameters

    • identifier: string

      The property identifier.

    • Optional value: string | number | boolean | Vector3

      Data value of the property to set.

      Optional

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

  • Parameters

    • seconds: number

      Length of time to set the entity on fire.

    • Optional 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.

      Optional

    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

    setEntityOnFire.ts

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

    function setAblaze(entity: Entity) {
    entity.setOnFire(20, true);

    system.runTimeout(() => {
    const onfire = entity.getComponent(EntityComponentTypes.OnFire);
    if (onfire) {
    world.sendMessage(`${onfire.onFireTicksRemaining} fire ticks remaining, extinguishing the entity.`);
    }
    // This will extinguish the entity
    entity.extinguishFire(true);
    }, 30); // Run in 30 ticks or ~1.5 seconds

    }

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

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

  • Parameters

    • location: Vector3

      New location for the entity.

    • Optional teleportOptions: TeleportOptions

      Options regarding the teleport operation.

      Optional

    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

    teleportMovement.ts

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

    const overworld = world.getDimension('overworld');
    const targetLocation = { x: 0, y: 0, z: 0 };

    const pig = overworld.spawnEntity('minecraft: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 },
    }
    );
    }
    });

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

  • Parameters

    • location: Vector3

      Location to teleport the entity to.

    • Optional teleportOptions: TeleportOptions

      Options regarding the teleport operation.

      Optional

    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.