#Class: Entity

Beta

表示世界中实体（生物、玩家或其他移动物体，如矿车）的状态。

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

#Extended by

• Player

#Properties

#dimension

readonly dimension: Dimension

Beta

#Remarks

实体当前所在的维度。

Dimension that the entity is currently within.

#Throws

This property can throw when used.

EngineError

InvalidEntityError

#id

readonly id: string

Beta

#Remarks

实体的唯一标识符。此标识符旨在跨世界实例加载保持一致。不应从此唯一标识符的值和结构中推断任何含义——不要解析或解释它。即使 Entity.isValid 为 false，此属性也可访问。

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

Beta

#Remarks

实体是否接触可攀爬方块。例如，梯子旁的玩家或石墙旁的蜘蛛。

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

#Throws

This property can throw when used.

InvalidEntityError

#isFalling

readonly isFalling: boolean

Beta

#Remarks

实体是否具有大于 0 的摔落距离，或在滑翔时大于 1。

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

Beta

#Remarks

实体的任何部分是否在水方块内部。

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

#Throws

This property can throw when used.

InvalidEntityError

#isOnGround

readonly isOnGround: boolean

Beta

#Remarks

实体是否在实心方块顶部。此属性可能以意外方式表现。此属性在实体首次生成时始终为 true，如果实体没有重力，则此属性可能不正确。

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

Beta

#Remarks

如果为 true，实体当前正在睡觉。

If true, the entity is currently sleeping.

#Throws

This property can throw when used.

InvalidEntityError

#isSneaking

isSneaking: boolean

World Mutation Beta

#Remarks

实体是否正在潜行——即移动得较慢且较安静。

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

#isSprinting

readonly isSprinting: boolean

Beta

#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

Beta

#Remarks

实体是否处于游泳状态。例如，使用游泳动作的玩家或水中的鱼。

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

#Throws

This property can throw when used.

InvalidEntityError

#isValid

readonly isValid: boolean

Beta

#Remarks

返回实体是否可以被脚本操作。当玩家的 EntityLifetimeState 设置为 Loaded 时，该玩家被视为有效。

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

Beta

#Remarks

用于在 .lang 文件中本地化此实体名称的键。

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

Beta

#Remarks

实体的当前位置。

Current location of the entity.

#Throws

This property can throw when used.

InvalidEntityError

#nameplateDepthTested

nameplateDepthTested: boolean

World Mutation Beta

#Remarks

决定玩家名称标签是否应进行深度测试以确定可见性的布尔值。

Boolean which determines if the player nameplate should be depth tested for visibility.

#nameplateRenderDistance

nameplateRenderDistance: number

World Mutation Beta

#Remarks

决定此实体名称标签渲染距离的浮点数。

Float that determines the render distance of this entity's nameplate.

#nameTag

nameTag: string

World Mutation Beta

#Remarks

实体的给定名称。

Given name of the entity.

#scoreboardIdentity?

readonly optional scoreboardIdentity?: ScoreboardIdentity

Beta

#Remarks

返回表示此实体的记分板身份。实体被击杀后仍将保持有效。

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

#target?

readonly optional target?: Entity

Beta

#Remarks

获取或设置用作 AI 相关行为（如攻击）目标的实体。如果实体当前没有目标，则返回 undefined。

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.

InvalidEntityError

#typeId

readonly typeId: string

Beta

#Remarks

实体类型的标识符——例如，minecraft:skeleton。即使 Entity.isValid 为 false，此属性也可访问。

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

World Mutation Beta

#Parameters

#effectType

string | EffectType

要添加到实体的效果类型。

Type of effect to add to the entity.

#duration

number

效果应用的时间量（以 tick 为单位）。每秒有 20 tick。使用 TicksPerSecond 常量在 tick 和秒之间进行转换。值必须在 [0, 20000000] 范围内。范围：[1, 20000000]

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.

#Throws

This function can throw errors.

ArgumentOutOfBoundsError

InvalidArgumentError

InvalidEntityError

#Examples

spawnPoisonedVillager.ts

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

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

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

quickFoxLazyDog.ts

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

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

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

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

#addItem()

addItem(itemStack): ItemStack | undefined

World Mutation Beta

#Parameters

#itemStack

ItemStack

#Returns

ItemStack | undefined

如果物品已完全添加则返回 undefined，否则返回包含剩余数量的 ItemStack。

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.

#Throws

This function can throw errors.

ContainerRulesError

Error

InvalidEntityComponentError

InvalidEntityError

#addTag()

addTag(tag): boolean

World Mutation Beta

#Parameters

#tag

string

要添加的标签内容。标签必须少于 256 个字符。

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

#Returns

boolean

如果标签成功添加则返回 true。如果标签已存在于实体上，则可能失败。

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.

#Throws

This function can throw errors.

ArgumentOutOfBoundsError

InvalidEntityError

#Example

tagsQuery.ts

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

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

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

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

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

#applyDamage()

applyDamage(amount, options?): boolean

World Mutation Beta

#Parameters

#amount

number

要应用的伤害量。

Amount of damage to apply.

#options?

EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions

关于伤害来源的附加选项，可能为此实体添加额外效果或引发额外行为。

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

#Returns

boolean

实体是否受到任何伤害。如果实体无敌或应用的伤害小于或等于 0，则可能返回 false。

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.

#Throws

This function can throw errors.

EngineError

InvalidEntityError

UnsupportedFunctionalityError

#Example

applyDamageThenHeal.ts

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

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

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

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

#applyImpulse()

applyImpulse(vector): void

World Mutation Beta

#Parameters

#vector

Vector3

冲量向量。

Impulse vector.

#Returns

void

#Remarks

向实体的当前速度施加冲量向量。

Applies impulse vector to the current velocity of the entity.

#Throws

This function can throw errors.

ArgumentOutOfBoundsError

InvalidEntityError

#Example

applyImpulse.ts

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

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

  zombie.clearVelocity();

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

#applyKnockback()

applyKnockback(horizontalForce, verticalStrength): void

World Mutation Beta

#Parameters

#horizontalForce

VectorXZ

#verticalStrength

number

垂直向量的击退强度。

Knockback strength for the vertical vector.

#Returns

void

#Remarks

向实体的当前速度施加冲量向量。

Applies impulse vector to the current velocity of the entity.

#Throws

This function can throw errors.

InvalidEntityError

UnsupportedFunctionalityError

#Example

bounceSkeletons.ts

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

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

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

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

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

#clearDynamicProperties()

clearDynamicProperties(): void

Beta

#Returns

void

#Remarks

清除此实体上设置的所有动态属性。

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

#Throws

This function can throw errors.

InvalidEntityError

#clearVelocity()

clearVelocity(): void

World Mutation Beta

#Returns

void

#Remarks

将实体的当前速度设置为零。

Sets the current velocity of the Entity to zero.

#Throws

This function can throw errors.

InvalidEntityError

#Example

applyImpulse.ts

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

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

  zombie.clearVelocity();

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

#extinguishFire()

extinguishFire(useEffects?): boolean

World Mutation Beta

#Parameters

#useEffects?

boolean

是否显示与灭火相关的任何视觉效果。默认值：true

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

#Returns

boolean

返回实体是否曾着火。

Returns whether the entity was on fire.

#Remarks

如果实体着火，则将其灭火。请注意，你可以调用 getComponent('minecraft:onfire')，如果存在，则实体着火。

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.

#Throws

This function can throw errors.

InvalidEntityError

#Example

setOnFire.ts

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

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

  skelly.setOnFire(20, true);

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

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

#getAABB()

getAABB(): AABB

Beta

#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[]

Beta

#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

Beta

#Parameters

#options?

BlockRaycastOptions

射线投射的附加配置选项。

Additional configuration options for the ray cast.

#Returns

BlockRaycastHit | undefined

返回从此实体视线方向上相交的第一个方块。

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

#Remarks

返回从此实体视线方向上相交的第一个方块。

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

#Throws

This function can throw errors.

InvalidEntityError

#getBlockStandingOn()

getBlockStandingOn(options?): Block | undefined

Beta

#Parameters

#options?

GetBlocksStandingOnOptions

返回哪个方块的附加配置选项。

Additional configuration options for what block is returned.

#Returns

Block | undefined

最接近此实体中心的一个实心方块，此实体直接站在上面。如果实体正在飞行或跳跃，则为 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

Beta

#Type Parameters

#T

T extends string

#Parameters

#componentId

T

组件的标识符（例如，'minecraft:health'）。如果未指定命名空间前缀，则默认为 'minecraft:'。可用的组件 ID 可以在 EntityComponentTypes 枚举中找到。

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

如果组件存在于实体上则返回该组件，否则返回 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[]

Beta

#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

Beta

#Parameters

#identifier

string

属性标识符。

The property identifier.

#Returns

string | number | boolean | Vector3 | undefined

返回属性的值，如果属性尚未设置则返回 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[]

Beta

#Returns

string[]

此实体上设置的动态属性的字符串数组。

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

#Remarks

返回此实体上已使用的可用动态属性标识符集合。

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

#Throws

This function can throw errors.

InvalidEntityError

#getDynamicPropertyTotalByteCount()

getDynamicPropertyTotalByteCount(): number

Beta

#Returns

number

#Remarks

返回此实体当前存储的所有动态属性的总大小（以字节为单位）。包括键和值的大小。这对于诊断性能警告信号很有用——例如，如果一个实体有数兆字节的关联动态属性，它在各种设备上加载可能会很慢。

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

#Throws

This function can throw errors.

InvalidEntityError

#getEffect()

getEffect(effectType): Effect | undefined

Beta

#Parameters

#effectType

string | EffectType

效果标识符。

The effect identifier.

#Returns

Effect | undefined

指定效果的 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

返回实体上指定 EffectType 的效果，如果效果不存在则返回 undefined，如果效果类型不存在则抛出错误。

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.

InvalidArgumentError

InvalidEntityError

#getEffects()

getEffects(): Effect[]

Beta

#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[]

Beta

#Parameters

#options?

EntityRaycastOptions

射线投射的附加配置选项。

Additional configuration options for the ray cast.

#Returns

EntityRaycastHit[]

返回从此实体视线方向上的实体集合。

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

#Remarks

通过从此实体的视角执行射线投射，获取此实体正在注视的实体。

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

#Throws

This function can throw errors.

EngineError

InvalidArgumentError

InvalidEntityError

UnsupportedFunctionalityError

#getHeadLocation()

getHeadLocation(): Vector3

Beta

#Returns

Vector3

返回此实体头部组件的当前位置。

Returns the current location of the head component of this entity.

#Remarks

返回此实体头部组件的当前位置。

Returns the current location of the head component of this entity.

#Throws

This function can throw errors.

InvalidEntityError

#getProperty()

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

Beta

#Parameters

#identifier

string

实体属性标识符。

The entity Property identifier.

#Returns

string | number | boolean | undefined

返回当前属性值。对于枚举属性，返回字符串。对于浮点和整数属性，返回数字。对于未定义的属性，返回 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

获取一个实体属性值。如果该属性在同一个 tick 内使用 setProperty 函数设置，更新后的值将不会反映出来，直到下一个 tick。

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

Beta

#Returns

Vector2

返回包含此实体旋转的 Vec2（以度为单位）。

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

Beta

#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

Beta

#Returns

Vector3

返回实体的当前速度向量。

Returns the current velocity vector of the entity.

#Remarks

返回实体的当前速度向量。

Returns the current velocity vector of the entity.

#Throws

This function can throw errors.

InvalidEntityError

#Example

getFireworkVelocity.ts

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

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

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

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

#getViewDirection()

getViewDirection(): Vector3

Beta

#Returns

Vector3

返回实体的当前视线方向。

Returns the current view direction of the entity.

#Remarks

返回实体的当前视线方向。

Returns the current view direction of the entity.

#Throws

This function can throw errors.

InvalidEntityError

#hasComponent()

hasComponent(componentId): boolean

Beta

#Parameters

#componentId

string

要检索的组件的标识符（例如，'minecraft:rideable'）。如果未指定命名空间前缀，则默认为 'minecraft:'。

The identifier of the component (e.g., 'minecraft:rideable') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.

#Returns

boolean

如果指定组件存在于该实体上，则返回 true。

Returns true if the specified component is present on this entity.

#Remarks

如果指定组件存在于该实体上，则返回 true。

Returns true if the specified component is present on this entity.

#Throws

This function can throw errors.

InvalidEntityError

#hasTag()

hasTag(tag): boolean

Beta

#Parameters

#tag

string

要测试的标签标识符。

Identifier of the tag to test for.

#Returns

boolean

返回实体是否具有特定标签。

Returns whether an entity has a particular tag.

#Remarks

返回实体是否具有特定标签。

Returns whether an entity has a particular tag.

#Throws

This function can throw errors.

InvalidEntityError

#kill()

kill(): boolean

World Mutation Beta

#Returns

boolean

如果实体可以被击杀则返回 true（即使它已经死亡），否则返回 false。

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.

#Throws

This function can throw errors.

InvalidEntityError

#Example

tagsQuery.ts

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

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

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

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

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

#lookAt()

lookAt(targetLocation): void

World Mutation Beta

#Parameters

#targetLocation

Vector3

此实体应面向/注视的目标位置。

The target location that this entity should face/look towards.

#Returns

void

#Remarks

设置实体的旋转以面对目标位置。如果适用，俯仰和偏航都将被设置，例如对于生物，俯仰控制头部倾斜，偏航控制身体旋转。

Sets the rotation of the entity to face a target location. Both pitch and yaw will be set, if applicable, such as for mobs where the pitch controls the head tilt and the yaw controls the body rotation.

#Throws

This function can throw errors.

InvalidEntityError

UnsupportedFunctionalityError

#matches()

matches(options): boolean

Beta

#Parameters

#options

EntityQueryOptions

执行匹配的查询条件。

The query to perform the match against.

#Returns

boolean

如果实体匹配传入的 EntityQueryOptions 中的条件则返回 true，否则返回 false。

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

#Remarks

将实体与传入的选项进行匹配。如果 EntityQueryOptions 中未指定位置，则使用实体的位置进行匹配。

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.

InvalidArgumentError

InvalidEntityError

UnsupportedFunctionalityError

#playAnimation()

playAnimation(animationName, options?): void

World Mutation Beta

#Parameters

#animationName

string

动画标识符，例如 animation.creeper.swelling。

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.

#Throws

This function can throw errors.

InvalidEntityError

#remove()

remove(): void

World Mutation Beta

#Returns

void

#Remarks

立即从世界中移除实体。被移除的实体不会执行死亡动画或在移除时掉落战利品。

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

#Throws

This function can throw errors.

InvalidEntityError

UnsupportedFunctionalityError

#removeEffect()

removeEffect(effectType): boolean

World Mutation Beta

#Parameters

#effectType

string | EffectType

效果标识符。

The effect identifier.

#Returns

boolean

如果效果已被移除则返回 true。如果未找到效果或效果不存在则返回 false。

Returns true if the effect has been removed. Returns false if the effect is not found or does not exist.

#Remarks

移除实体上的指定 EffectType，如果效果不存在则返回 false。

Removes the specified EffectType on the entity, or returns false if the effect is not present.

#Throws

This function can throw errors.

InvalidArgumentError

InvalidEntityError

#removeTag()

removeTag(tag): boolean

World Mutation Beta

#Parameters

#tag

string

要移除的标签内容。

Content of the tag to remove.

#Returns

boolean

返回该标签是否存在于实体上。

Returns whether the tag existed on the entity.

#Remarks

从实体移除指定的标签。

Removes a specified tag from an entity.

#Throws

This function can throw errors.

InvalidEntityError

#resetProperty()

resetProperty(identifier): string | number | boolean

World Mutation Beta

#Parameters

#identifier

string

实体属性标识符。

The Entity Property identifier.

#Returns

string | number | boolean

返回默认属性值。对于枚举属性，返回字符串。对于浮点和整数属性，返回数字。对于未定义的属性，返回 undefined。

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

将实体属性重置为其默认值，如实体定义中所指定。此属性更改直到下一个 tick 才会应用。

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.

#Throws

如果实体无效则抛出异常。

Throws if the entity is invalid.

EngineError

Error

InvalidEntityError

#runCommand()

runCommand(commandString): CommandResult

World Mutation Beta

#Parameters

#commandString

string

命令字符串。注意：这不应包含前导斜杠。

The command string. Note: This should not include a leading forward slash.

#Returns

CommandResult

包含命令是否成功的命令结果。

A command result containing whether the command was successful.

#Remarks

在实体上运行同步命令。

Runs a synchronous command on the entity.

#Throws

This function can throw errors.

CommandError

InvalidEntityError

#setDynamicProperties()

setDynamicProperties(values): void

Beta

#Parameters

#values

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

要设置的动态属性的键值对记录。如果数据值为 null，将会移除该属性。

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.

ArgumentOutOfBoundsError

InvalidEntityError

#setDynamicProperty()

setDynamicProperty(identifier, value?): void

Beta

#Parameters

#identifier

string

属性标识符。

The property identifier.

#value?

string | number | boolean | Vector3

要设置的属性的数据值。如果值为 null，将会移除该属性。

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.

ArgumentOutOfBoundsError

InvalidEntityError

#setOnFire()

setOnFire(seconds, useEffects?): boolean

World Mutation Beta

#Parameters

#seconds

number

设置实体着火的时间长度。

Length of time to set the entity on fire.

#useEffects?

boolean

是否应考虑副作用（如解冻）和其他条件，如雨水或防火保护。默认值：true

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

点燃实体（如果它不在水中或雨里）。请注意，你可以调用 getComponent('minecraft:onfire')，如果存在，则实体着火。

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.

#Throws

This function can throw errors.

InvalidEntityError

#Example

setOnFire.ts

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

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

  skelly.setOnFire(20, true);

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

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

#setProperty()

setProperty(identifier, value): void

World Mutation Beta

#Parameters

#identifier

string

实体属性标识符。

The Entity Property identifier.

#value

string | number | boolean

属性值。提供的类型必须与实体定义中指定的类型兼容。

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

#Returns

void

#Remarks

将实体属性设置为提供的值。此属性更改直到下一个 tick 才会应用。

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

#Throws

如果实体无效则抛出异常。如果提供了无效的标识符则抛出异常。如果提供的值类型与属性类型不匹配则抛出异常。如果提供的值超出预期范围（int、float 属性）则抛出异常。如果提供的字符串值与接受的枚举值集合不匹配（枚举属性）则抛出异常。

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

ArgumentOutOfBoundsError

InvalidArgumentError

InvalidEntityError

#setRotation()

setRotation(rotation): void

World Mutation Beta

#Parameters

#rotation

Vector2

实体的 x 和 y 旋转（以度为单位）。对于大多数生物，x 旋转控制头部倾斜，y 旋转控制身体旋转。

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.

#Throws

This function can throw errors.

InvalidEntityError

#teleport()

teleport(location, teleportOptions?): void

World Mutation Beta

#Parameters

#location

Vector3

实体的新位置。

New location for the entity.

#teleportOptions?

TeleportOptions

关于传送操作的选项。

Options regarding the teleport operation.

#Returns

void

#Remarks

将选定的实体传送到新位置。

Teleports the selected entity to a new location

#Throws

This function can throw errors.

InvalidEntityError

UnsupportedFunctionalityError

#Examples

teleport.ts

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

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

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

teleportMovement.ts

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

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

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

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

#triggerEvent()

triggerEvent(eventName): void

World Mutation Beta

#Parameters

#eventName

string

要触发的实体类型事件的名称。如果未指定命名空间，则默认为 minecraft:。

Name of the entity type event to trigger. If a namespace is not specified, minecraft: is assumed.

#Returns

void

#Remarks

触发一个实体类型事件。对于每个实体，在实体的定义为关键实体行为定义了许多事件；例如，苦力怕有一个 minecraft:start_exploding 类型事件。

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.

#Throws

如果事件未在实体的定义中定义，则会抛出错误。

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

InvalidArgumentError

InvalidEntityError

#Examples

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

triggerEvent.ts

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

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

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

#tryTeleport()

tryTeleport(location, teleportOptions?): boolean

World Mutation Beta

#Parameters

#location

Vector3

要传送实体的位置。

Location to teleport the entity to.

#teleportOptions?

TeleportOptions

关于传送操作的选项。

Options regarding the teleport operation.

#Returns

boolean

返回传送是否成功。如果目标区块未加载或传送会导致与方块相交，则可能失败。

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

#Remarks

尝试传送，但可能不会完成传送操作（例如，如果目标位置有方块阻挡）。

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

#Throws

This function can throw errors.

InvalidEntityError

UnsupportedFunctionalityError

#同领域相关

• BlockComponentEntityEvent
• BlockComponentEntityFallOnEvent
• CarryOverBlockEntityDataFunction
• DamagedByEntityCondition
• DataDrivenEntityTriggerAfterEvent
• DataDrivenEntityTriggerAfterEventSignal