Class Entity

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

Hierarchy (View Summary)

Entity
- Player

Properties

`Readonly`dimension

dimension: Dimension

Remarks

Dimension that the entity is currently within.

Throws

This property can throw when used.

Example: spawnTnt.js

import { ItemStack } from "@minecraft/server";
entity.dimension.spawnItem(
    new ItemStack("minecraft:diamond_sword"),
    entity.location
);

`Readonly` `Beta`fallDistance

fallDistance: number

Remarks

The distance an entity has fallen. The value is reset when the entity is teleported. The value is always 1 when gliding with Elytra.

Throws

This property can throw when used.

`Readonly`id

id: string

Remarks

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

system.runInterval(() => {
    const entity = world.getEntity("unique_id");
    if (entity.isSneaking) {
        // force entity not to sneak
        entity.isSneaking = false;
    }
});

`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

entity.runCommandAsync("say isClimbing: " + entity.isClimbing);

`Readonly`isInWater

isInWater: boolean

Remarks

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

Throws

This property can throw when used.

`Readonly`isOnGround

isOnGround: boolean

Remarks

Whether the entity is on top of a solid block.

Throws

This property can throw when used.

`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: debug.js

entity.runCommandAsync("say isClimbing: " + entity.isClimbing);

`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` `Beta`lifetimeState

lifetimeState: EntityLifetimeState

Remarks

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

`Readonly`location

location: Vector3

Remarks

Current location of the entity.

Throws

This property can throw when used.

Example: showLocation.js

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

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

nameTag

nameTag: string

Remarks

Given name of the entity.

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

`Optional` `Readonly`scoreboardIdentity

scoreboardIdentity?: ScoreboardIdentity

Remarks

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

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

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: addEffect.js

const villagerId = 'minecraft:villager_v2<minecraft:ageable_grow_up>';
const villagerLoc: mc.Vector3 = { x: 1, y: 2, z: 1 };
const villager = test.spawn(villagerId, villagerLoc);
const duration = 20;

villager.addEffect(EffectTypes.get('poison'), duration, { amplifier: 1 });

Example: quickFoxLazyDog.ts

  const overworld = mc.world.getDimension("overworld");

  const fox = overworld.spawnEntity("minecraft:fox", {
    x: targetLocation.x + 1,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
  });

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

  const wolf = overworld.spawnEntity("minecraft:wolf", {
    x: targetLocation.x + 4,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
  });
  wolf.addEffect("slowness", 10, {
    amplifier: 2,
  });
  wolf.isSneaking = true;
  log("Created a sneaking wolf.", 1);

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

  let mobs = ["creeper", "skeleton", "sheep"];

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

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

  for (let entity of overworld.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

  const skelly = overworld.spawnEntity("minecraft:skeleton", targetLocation);

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

  mc.system.runTimeout(() => {
    let health = skelly.getComponent("health") as mc.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

const damageApplied = entity.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
```
  const zombie = overworld.spawnEntity("minecraft: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
```
  let mobs = ["creeper", "skeleton", "sheep"];

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

  let eqo: mc.EntityQueryOptions = {
    type: "skeleton",
  };

  for (let entity of overworld.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
```
entity.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
```
  const zombie = overworld.spawnEntity("minecraft:zombie", targetLocation);

  zombie.clearVelocity();

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

extinguishFire

extinguishFire(useEffects?: boolean): boolean

Beta

Parameters

OptionaluseEffects: boolean
Whether to show any visual effects connected to the extinguishing.

Returns boolean

Returns whether the entity was on fire.

Remarks

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

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

Throws

This function can throw errors.

Example: setOnFire.ts

  const skelly = overworld.spawnEntity("minecraft:skeleton", targetLocation);

  skelly.setOnFire(20, true);

  mc.system.runTimeout(() => {
    let onfire = skelly.getComponent("onfire") as mc.EntityOnFireComponent;
    log(onfire.onFireTicksRemaining + " fire ticks remaining.");

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

Example: teleport.ts

  const cow = overworld.spawnEntity("minecraft:cow", targetLocation);

  mc.system.runTimeout(() => {
    cow.teleport(
      { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 2 },
      {
        facingLocation: targetLocation,
      }
    );
  }, 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

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: getEntityHealthComponent.js

const getEntityHealthComponent = entity.getComponent("health");
getEntityHealthComponent.currentValue;
getEntityHealthComponent.defaultValue;
getEntityHealthComponent.effectiveMax;
getEntityHealthComponent.effectiveMin;
getEntityHealthComponent.resetToDefaultValue();
getEntityHealthComponent.resetToMaxValue();
getEntityHealthComponent.resetToMinValue();
getEntityHealthComponent.setCurrentValue(100); // Assuming 100 as an example value

// Custom function to check if the health attribute is within a valid range
function isValidHealthValue(value) {
    return (
        value >= getEntityHealthComponent.effectiveMin &&
        value <= getEntityHealthComponent.effectiveMax
    );
}

// Example usage of the custom isValidHealthValue function
const newHealthValue = 80;
if (isValidHealthValue(newHealthValue)) {
    getEntityHealthComponent.setCurrentValue(newHealthValue);
}

Example: getEntityInventoryComponent.js

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

const getEntityInventoryComponent = entity.getComponent("inventory");
getEntityInventoryComponent.additionalSlotsPerStrength;
getEntityInventoryComponent.canBeSiphonedFrom;
const inventoryContainer = getEntityInventoryComponent.container;
getEntityInventoryComponent.containerType;
getEntityInventoryComponent.inventorySize;
getEntityInventoryComponent.private;
getEntityInventoryComponent.restrictToOwner;
getEntityInventoryComponent.isValid();

// Custom function to add an item to the inventory
function addItemToInventory(itemStack) {
    return inventoryContainer.addItem(itemStack);
}

// Custom function to move an item within the inventory
function moveItemWithinInventory(fromSlot, toSlot) {
    inventoryContainer.moveItem(fromSlot, toSlot, inventoryContainer);
}

// Custom function to transfer an item from inventory to another container
function transferItemToContainer(fromSlot, targetContainer) {
    return inventoryContainer.transferItem(fromSlot, targetContainer);
}

// Example usage of the custom functions
const newItemStack = new ItemStack("apple", 10); // Assuming "apple" is a valid item
const addedItem = addItemToInventory(newItemStack);
if (addedItem) {
    console.log("Item added to inventory:", addedItem);
}

const sourceSlot = 2;
const destinationSlot = 5;
moveItemWithinInventory(sourceSlot, destinationSlot);

const targetContainer = someOtherContainer; // Assuming 'someOtherContainer' is an instance of another container
const transferredItem = transferItemToContainer(0, targetContainer);
if (transferredItem) {
    console.log("Item transferred to another container:", transferredItem);
}

Example: getEntityItemComponent.js

const getEntityItemComponent = itemEntity.getComponent("item");
getEntityItemComponent.itemStack;
getEntityItemComponent.isValid();

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
```
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.js

import { 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) => {
    // @ts-ignore
    const location = event.removedEntity.getDynamicProperty("spawn_location"); // get location spawn
    system.run(() => {
        event.removedEntity.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.

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.

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

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

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

// Perform the ray cast
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
});

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.

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
```
entity.setProperty("create:rotation_offset", 1);
console.warn(entity.getProperty("create:rotation_offset"));
```

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
```
const rotation = entity.getRotation();
rotation.x;
rotation.y;
```

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
```
const tags = entity.getTags();
const jaylyTag = tags.find((tag) => tag.startsWith("jayly:"));
```

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

  const fireworkRocket = overworld.spawnEntity("minecraft:fireworks_rocket", targetLocation);

  mc.system.runTimeout(() => {
    let 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.

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
```
entity.hasComponent("tameable");
entity.hasComponent("inventory");
entity.hasComponent("addrider");
entity.hasComponent("is_tamed");
```

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.

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.

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

  let mobs = ["creeper", "skeleton", "sheep"];

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

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

  for (let entity of overworld.getEntities(eqo)) {
    entity.kill();
  }

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 } from "@minecraft/server";
entity.matches({ gameMode: GameMode.spectator });
```

playAnimation

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

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

Throws
This function can throw errors.

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.

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.

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.

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

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

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.

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

import { 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) => {
    // @ts-ignore
    const location = event.removedEntity.getDynamicProperty("spawn_location"); // get location spawn
    system.run(() => {
        event.removedEntity.dimension.spawnEntity(
            event.removedEntity.typeId,
            location
        );
    });
});

setOnFire

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

Beta

Parameters

seconds: number
Length of time to set the entity on fire.
OptionaluseEffects: boolean
Whether side-effects should be applied (e.g. thawing freeze) and other conditions such as rain or fire protection should be taken into consideration.

Returns boolean

Whether the entity was set on fire. This can fail if seconds is less than or equal to zero, the entity is wet or the entity is immune to fire.

Remarks

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

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

Throws

This function can throw errors.

Example: setOnFire.ts

  const skelly = overworld.spawnEntity("minecraft:skeleton", targetLocation);

  skelly.setOnFire(20, true);

  mc.system.runTimeout(() => {
    let onfire = skelly.getComponent("onfire") as mc.EntityOnFireComponent;
    log(onfire.onFireTicksRemaining + " fire ticks remaining.");

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

Example: teleport.ts

  const cow = overworld.spawnEntity("minecraft:cow", targetLocation);

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

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
```
tileEntity.setProperty("create:rotation_offset", 1);
console.warn(tileEntity.getProperty("create:rotation_offset"));
```

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.

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

  const pig = overworld.spawnEntity("minecraft:pig", targetLocation);

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

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

Example: teleport.js

player.teleport(
    { x: 0, y: 0, z: 0 },
    { dimension: world.getDimension("nether") }
);

Example: teleportFacing.js

player.teleport(
    { x: 0, y: 0, z: 0 },
    {
        dimension: world.getDimension("nether"),
        teleportFacing: { 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
```
  const creeper = overworld.spawnEntity("minecraft: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.

Class Entity

Hierarchy (View Summary)

Index

Properties

Methods

Properties

Readonlydimension

Remarks

Throws

Example: spawnTnt.js

Readonly BetafallDistance

Remarks

Throws

Readonlyid

Remarks

Example: trapEntity.js

ReadonlyisClimbing

Remarks

Throws

Example: debug.js

ReadonlyisFalling

Remarks

Throws

Example: debug.js

ReadonlyisInWater

Remarks

Throws

ReadonlyisOnGround

Remarks

Throws

ReadonlyisSleeping

Remarks

Throws

isSneaking

Remarks

Example: debug.js

ReadonlyisSprinting

Remarks

Throws

ReadonlyisSwimming

Remarks

Throws

Readonly BetalifetimeState

Remarks

Readonlylocation

Remarks

Throws

Example: showLocation.js

nameTag

Remarks

Optional ReadonlyscoreboardIdentity

Remarks

Optional Readonly Betatarget

Remarks

Throws

ReadonlytypeId

Remarks

Example: showLocation.js

Methods

addEffect

Parameters

Returns Effect

Remarks

Throws

Example: addEffect.js

Example: quickFoxLazyDog.ts

addTag

Parameters

Returns boolean

Remarks

Throws

Example: tagsQuery.ts

applyDamage

Parameters

Returns boolean

Remarks

Throws

Example: applyDamageThenHeal.ts

Example: applyWither.js

Example: damageEntity.js

`Readonly`dimension

`Readonly` `Beta`fallDistance

`Readonly`id

`Readonly`isClimbing

`Readonly`isFalling

`Readonly`isInWater

`Readonly`isOnGround

`Readonly`isSleeping

`Readonly`isSprinting

`Readonly`isSwimming

`Readonly` `Beta`lifetimeState

`Readonly`location

`Optional` `Readonly`scoreboardIdentity

`Optional` `Readonly` `Beta`target

`Readonly`typeId