Bedrock API Reference

Appearance

@minecraft/server

@minecraft/server / Entity

Class: Entity ​

Defined in: @minecraft/server/index.d.ts:8436

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

Extended by ​

Properties ​

dimension ​

readonly dimension: Dimension

Defined in: @minecraft/server/index.d.ts:8448

Remarks ​

Dimension that the entity is currently within.

Throws ​

This property can throw when used.

minecraftcommon.EngineError

InvalidEntityError

id ​

readonly id: string

Defined in: @minecraft/server/index.d.ts:8459

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.

isClimbing ​

readonly isClimbing: boolean

Defined in: @minecraft/server/index.d.ts:8470

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.

InvalidEntityError

isFalling ​

readonly isFalling: boolean

Defined in: @minecraft/server/index.d.ts:8480

Remarks ​

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

Throws ​

This property can throw when used.

InvalidEntityError

isInWater ​

readonly isInWater: boolean

Defined in: @minecraft/server/index.d.ts:8489

Remarks ​

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

Throws ​

This property can throw when used.

InvalidEntityError

isOnGround ​

readonly isOnGround: boolean

Defined in: @minecraft/server/index.d.ts:8501

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.

InvalidEntityError

isSleeping ​

readonly isSleeping: boolean

Defined in: @minecraft/server/index.d.ts:8510

Remarks ​

If true, the entity is currently sleeping.

Throws ​

This property can throw when used.

InvalidEntityError

isSneaking ​

isSneaking: boolean

Defined in: @minecraft/server/index.d.ts:8519

Remarks ​

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

This property can't be edited in restricted-execution mode.

isSprinting ​

readonly isSprinting: boolean

Defined in: @minecraft/server/index.d.ts:8530

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.

InvalidEntityError

isSwimming ​

readonly isSwimming: boolean

Defined in: @minecraft/server/index.d.ts:8540

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.

InvalidEntityError

isValid ​

readonly isValid: boolean

Defined in: @minecraft/server/index.d.ts:8548

Remarks ​

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

localizationKey ​

readonly localizationKey: string

Defined in: @minecraft/server/index.d.ts:8558

Remarks ​

Key for the localization of this entity's name used in .lang files.

Throws ​

This property can throw when used.

InvalidEntityError

location ​

readonly location: Vector3

Defined in: @minecraft/server/index.d.ts:8567

Remarks ​

Current location of the entity.

Throws ​

This property can throw when used.

InvalidEntityError

nameTag ​

nameTag: string

Defined in: @minecraft/server/index.d.ts:8575

Remarks ​

Given name of the entity.

This property can't be edited in restricted-execution mode.

scoreboardIdentity? ​

readonly optional scoreboardIdentity?: ScoreboardIdentity

Defined in: @minecraft/server/index.d.ts:8582

Remarks ​

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

typeId ​

readonly typeId: string

Defined in: @minecraft/server/index.d.ts:8590

Remarks ​

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

Methods ​

addEffect() ​

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

Defined in: @minecraft/server/index.d.ts:8662

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]. Bounds: [1, 20000000]

options? ​

EntityEffectOptions

Additional options for the effect.

Returns ​

Effect | undefined

Returns nothing if the effect was added or updated successfully. This can throw an error if the duration or amplifier are outside of the valid ranges, or if the effect does not exist.

Remarks ​

Adds or updates an effect, like poison, to the entity.

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

minecraftcommon.InvalidArgumentError

InvalidEntityError

Examples ​

spawnPoisonedVillager.ts

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

quickFoxLazyDog.ts

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

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

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

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

addItem() ​

addItem(itemStack): ItemStack | undefined

Defined in: @minecraft/server/index.d.ts:8682

Parameters ​

itemStack ​

ItemStack

Returns ​

ItemStack | undefined

Returns undefined if the item was fully added or returns an ItemStack with the remaining count.

Remarks ​

Adds an item to the entity's inventory.

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

ContainerRulesError

Error

InvalidEntityComponentError

InvalidEntityError

addTag() ​

addTag(tag): boolean

Defined in: @minecraft/server/index.d.ts:8724

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 restricted-execution mode.

Throws ​

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

InvalidEntityError

Example ​

tagsQuery.ts

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

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

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

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

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

applyDamage() ​

applyDamage(amount, options?): boolean

Defined in: @minecraft/server/index.d.ts:8767

Parameters ​

amount ​

number

Amount of damage to apply.

options? ​

EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions

Additional options about the source of damage, which may add additional effects or spur additional behaviors on this entity.

Returns ​

boolean

Whether the entity takes any damage. This can return false if the entity is invulnerable or if the damage applied is less than or equal to 0.

Remarks ​

Applies a set of damage to an entity.

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

minecraftcommon.EngineError

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError

Example ​

applyDamageThenHeal.ts

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

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

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

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

applyImpulse() ​

applyImpulse(vector): void

Defined in: @minecraft/server/index.d.ts:8797

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 restricted-execution mode.

Throws ​

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

InvalidEntityError

Example ​

applyImpulse.ts

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

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

  zombie.clearVelocity();

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

applyKnockback() ​

applyKnockback(horizontalForce, verticalStrength): void

Defined in: @minecraft/server/index.d.ts:8834

Parameters ​

horizontalForce ​

VectorXZ

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 restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError

Example ​

bounceSkeletons.ts

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

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

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

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

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

clearDynamicProperties() ​

clearDynamicProperties(): void

Defined in: @minecraft/server/index.d.ts:8844

Returns ​

void

Remarks ​

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

Throws ​

This function can throw errors.

InvalidEntityError

clearVelocity() ​

clearVelocity(): void

Defined in: @minecraft/server/index.d.ts:8869

Returns ​

void

Remarks ​

Sets the current velocity of the Entity to zero.

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

Example ​

applyImpulse.ts

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

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

  zombie.clearVelocity();

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

extinguishFire() ​

extinguishFire(useEffects?): boolean

Defined in: @minecraft/server/index.d.ts:8907

Parameters ​

useEffects? ​

boolean

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

Returns ​

boolean

Returns whether the entity was on fire.

Remarks ​

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

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

Example ​

setOnFire.ts

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

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

  skelly.setOnFire(20, true);

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

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

getAABB() ​

getAABB(): AABB

Defined in: @minecraft/server/index.d.ts:8918

Returns ​

AABB

An axis-aligned bounding box.

Remarks ​

Gets the entity's collision bounds.

Throws ​

This function can throw errors.

InvalidEntityError

getAllBlocksStandingOn() ​

getAllBlocksStandingOn(options?): Block[]

Defined in: @minecraft/server/index.d.ts:8934

Parameters ​

options? ​

GetBlocksStandingOnOptions

Additional configuration options for what blocks are returned.

Returns ​

Block[]

The solid blocks that this entity is directly standing on. Returns an empty list if the entity is jumping or flying.

Remarks ​

Gets the solid blocks that this entity is directly standing on. Ignores pressure plates.

Throws ​

This function can throw errors.

InvalidEntityError

getBlockFromViewDirection() ​

getBlockFromViewDirection(options?): BlockRaycastHit | undefined

Defined in: @minecraft/server/index.d.ts:8949

Parameters ​

options? ​

BlockRaycastOptions

Additional configuration options for the ray cast.

Returns ​

BlockRaycastHit | undefined

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

Remarks ​

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

Throws ​

This function can throw errors.

InvalidEntityError

getBlockStandingOn() ​

getBlockStandingOn(options?): Block | undefined

Defined in: @minecraft/server/index.d.ts:8966

Parameters ​

options? ​

GetBlocksStandingOnOptions

Additional configuration options for what block is returned.

Returns ​

Block | undefined

A single solid block closest to the center of the entity that this entity is directly standing on. Undefined if entity is flying or jumping.

Remarks ​

Gets a single solid block closest to the center of the entity that this entity is directly standing on. Ignores pressure plates.

Throws ​

This function can throw errors.

InvalidEntityError

getComponent() ​

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

Defined in: @minecraft/server/index.d.ts:8984

Type Parameters ​

T ​

T extends string

Parameters ​

componentId ​

T

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

Returns ​

EntityComponentReturnType<T> | undefined

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

Remarks ​

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

Throws ​

This function can throw errors.

InvalidEntityError

getComponents() ​

getComponents(): EntityComponent[]

Defined in: @minecraft/server/index.d.ts:8994

Returns ​

EntityComponent[]

Remarks ​

Returns all scripting components that are present on this entity.

Throws ​

This function can throw errors.

InvalidEntityError

getDynamicProperty() ​

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

Defined in: @minecraft/server/index.d.ts:9008

Parameters ​

identifier ​

string

The property identifier.

Returns ​

string | number | boolean | Vector3 | undefined

Returns the value for the property, or undefined if the property has not been set.

Remarks ​

Returns a property value.

Throws ​

This function can throw errors.

InvalidEntityError

getDynamicPropertyIds() ​

getDynamicPropertyIds(): string[]

Defined in: @minecraft/server/index.d.ts:9020

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.

InvalidEntityError

getDynamicPropertyTotalByteCount() ​

getDynamicPropertyTotalByteCount(): number

Defined in: @minecraft/server/index.d.ts:9034

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.

InvalidEntityError

getEffect() ​

getEffect(effectType): Effect | undefined

Defined in: @minecraft/server/index.d.ts:9053

Parameters ​

effectType ​

string | EffectType

The effect identifier.

Returns ​

Effect | undefined

Effect object for the specified effect, undefined if the effect is not present, or throws an error if the effect does not exist.

Remarks ​

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

Throws ​

This function can throw errors.

minecraftcommon.InvalidArgumentError

InvalidEntityError

getEffects() ​

getEffects(): Effect[]

Defined in: @minecraft/server/index.d.ts:9064

Returns ​

Effect[]

List of effects.

Remarks ​

Returns a set of effects applied to this entity.

Throws ​

This function can throw errors.

InvalidEntityError

getEntitiesFromViewDirection() ​

getEntitiesFromViewDirection(options?): EntityRaycastHit[]

Defined in: @minecraft/server/index.d.ts:9085

Parameters ​

options? ​

EntityRaycastOptions

Additional configuration options for the ray cast.

Returns ​

EntityRaycastHit[]

Returns a set of entities from the direction that this entity is looking at.

Remarks ​

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

Throws ​

This function can throw errors.

minecraftcommon.EngineError

minecraftcommon.InvalidArgumentError

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError

getHeadLocation() ​

getHeadLocation(): Vector3

Defined in: @minecraft/server/index.d.ts:9098

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.

InvalidEntityError

getProperty() ​

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

Defined in: @minecraft/server/index.d.ts:9117

Parameters ​

identifier ​

string

The entity Property identifier.

Returns ​

string | number | boolean | undefined

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

Remarks ​

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

Throws ​

Throws if the entity is invalid.

InvalidEntityError

getRotation() ​

getRotation(): Vector2

Defined in: @minecraft/server/index.d.ts:9129

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.

InvalidEntityError

getTags() ​

getTags(): string[]

Defined in: @minecraft/server/index.d.ts:9140

Returns ​

string[]

An array containing all tags as strings.

Remarks ​

Returns all tags associated with the entity.

Throws ​

This function can throw errors.

InvalidEntityError

getVelocity() ​

getVelocity(): Vector3

Defined in: @minecraft/server/index.d.ts:9166

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.

InvalidEntityError

Example ​

getFireworkVelocity.ts

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

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

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

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

getViewDirection() ​

getViewDirection(): Vector3

Defined in: @minecraft/server/index.d.ts:9177

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.

InvalidEntityError

hasComponent() ​

hasComponent(componentId): boolean

Defined in: @minecraft/server/index.d.ts:9194

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.

Throws ​

This function can throw errors.

InvalidEntityError

hasTag() ​

hasTag(tag): boolean

Defined in: @minecraft/server/index.d.ts:9207

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.

InvalidEntityError

kill() ​

kill(): boolean

Defined in: @minecraft/server/index.d.ts:9244

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 restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

Example ​

tagsQuery.ts

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

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

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

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

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

lookAt() ​

lookAt(targetLocation): void

Defined in: @minecraft/server/index.d.ts:9263

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 restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError

matches() ​

matches(options): boolean

Defined in: @minecraft/server/index.d.ts:9284

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.

minecraftcommon.InvalidArgumentError

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError

playAnimation() ​

playAnimation(animationName, options?): void

Defined in: @minecraft/server/index.d.ts:9300

Parameters ​

animationName ​

string

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

options? ​

PlayAnimationOptions

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

Returns ​

void

Remarks ​

Cause the entity to play the given animation.

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

remove() ​

remove(): void

Defined in: @minecraft/server/index.d.ts:9315

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 restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError

removeEffect() ​

removeEffect(effectType): boolean

Defined in: @minecraft/server/index.d.ts:9334

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 restricted-execution mode.

Throws ​

This function can throw errors.

minecraftcommon.InvalidArgumentError

InvalidEntityError

removeTag() ​

removeTag(tag): boolean

Defined in: @minecraft/server/index.d.ts:9349

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 restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

resetProperty() ​

resetProperty(identifier): string | number | boolean

Defined in: @minecraft/server/index.d.ts:9374

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 restricted-execution mode.

Throws ​

Throws if the entity is invalid.

minecraftcommon.EngineError

Error

InvalidEntityError

runCommand() ​

runCommand(commandString): CommandResult

Defined in: @minecraft/server/index.d.ts:9393

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 restricted-execution mode.

Throws ​

This function can throw errors.

CommandError

InvalidEntityError

setDynamicProperties() ​

setDynamicProperties(values): void

Defined in: @minecraft/server/index.d.ts:9408

Parameters ​

values ​

Record<string, boolean | number | string | Vector3 | undefined>

A Record of key value pairs of the dynamic properties to set. If the data value is null, it will remove that property instead.

Returns ​

void

Remarks ​

Sets multiple dynamic properties with specific values.

Throws ​

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

InvalidEntityError

setDynamicProperty() ​

setDynamicProperty(identifier, value?): void

Defined in: @minecraft/server/index.d.ts:9424

Parameters ​

identifier ​

string

The property identifier.

value? ​

string | number | boolean | Vector3

Data value of the property to set. If the value is null, it will remove the property instead.

Returns ​

void

Remarks ​

Sets a specified property to a value.

Throws ​

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

InvalidEntityError

setOnFire() ​

setOnFire(seconds, useEffects?): boolean

Defined in: @minecraft/server/index.d.ts:9467

Parameters ​

seconds ​

number

Length of time to set the entity on fire.

useEffects? ​

boolean

Whether side-effects should be applied (e.g. thawing freeze) and other conditions such as rain or fire protection should be taken into consideration. Defaults to: true

Returns ​

boolean

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

Remarks ​

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

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

Example ​

setOnFire.ts

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

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

  skelly.setOnFire(20, true);

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

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

setProperty() ​

setProperty(identifier, value): void

Defined in: @minecraft/server/index.d.ts:9496

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 restricted-execution 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

minecraftcommon.ArgumentOutOfBoundsError

minecraftcommon.InvalidArgumentError

InvalidEntityError

setRotation() ​

setRotation(rotation): void

Defined in: @minecraft/server/index.d.ts:9511

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 restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

teleport() ​

teleport(location, teleportOptions?): void

Defined in: @minecraft/server/index.d.ts:9570

Parameters ​

location ​

Vector3

New location for the entity.

teleportOptions? ​

TeleportOptions

Options regarding the teleport operation.

Returns ​

void

Remarks ​

Teleports the selected entity to a new location

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError

Examples ​

teleport.ts

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

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

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

teleportMovement.ts

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

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

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

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

triggerEvent() ​

triggerEvent(eventName): void

Defined in: @minecraft/server/index.d.ts:9614

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 restricted-execution mode.

Throws ​

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

minecraftcommon.InvalidArgumentError

InvalidEntityError

Examples ​

triggerEvent.ts

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

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

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

triggerEvent.ts

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

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

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

tryTeleport() ​

tryTeleport(location, teleportOptions?): boolean

Defined in: @minecraft/server/index.d.ts:9637

Parameters ​

location ​

Vector3

Location to teleport the entity to.

teleportOptions? ​

TeleportOptions

Options regarding the teleport operation.

Returns ​

boolean

Returns whether the teleport succeeded. This can fail if the destination chunk is unloaded or if the teleport would result in intersecting with blocks.

Remarks ​

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

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

InvalidEntityError

minecraftcommon.UnsupportedFunctionalityError