#Class: Player

Beta

表示世界中的一个玩家。

Represents a player within the world.

#Extends

• Entity

#Properties

#camera

readonly camera: Camera

Beta

#Remarks

玩家的摄像机。

The player's Camera.

#Throws

This property can throw when used.

#chatDisplayName

readonly chatDisplayName: string

Beta

#Remarks

玩家的聊天显示名称，由 Player.chatNamePrefix + Player.name + Player.chatNameSuffix 组成。这是以此玩家身份发送的聊天消息中所显示的作者名称。要更改显示在玩家头顶的名称，请使用 Entity.nameTag。

The player's chat display name, composed from Player.chatNamePrefix + Player.name + Player.chatNameSuffix. This is the name shown as the author of chat messages sent by this player. To change the name shown above the player's head, use Entity.nameTag.

#Throws

This property can throw when used.

InvalidEntityError

#chatMessagePrefix?

optional chatMessagePrefix?: string

Beta World Mutation

#Remarks

一个可选的字符串，设置后会被添加到该玩家发送的聊天消息文本之前。可用于对玩家的消息应用格式或颜色代码（例如，使用 '§a' 使其消息变为绿色）。不影响玩家的名称显示 —— 请使用 Player.chatNamePrefix 更改聊天中显示的名称，或使用 Entity.nameTag 更改玩家头顶的名称。设置为 undefined 以清除。

An optional string that, when set, is prepended to the text of chat messages sent by this player. Useful for applying formatting or color codes to a player's messages (e.g., '§a' to make their messages green). Does not affect the player's name display - use Player.chatNamePrefix for the name shown in chat, or Entity.nameTag for the name above the player's head. Set to undefined to clear.

#chatNamePrefix?

optional chatNamePrefix?: string

Beta World Mutation

#Remarks

一个可选的字符串，设置后会被添加到聊天消息中玩家的名称之前。不影响玩家头顶的名称标签或玩家列表 —— 请使用 Entity.nameTag 设置。要为消息文本本身添加前缀，请使用 Player.chatMessagePrefix。设置为 undefined 以清除。

An optional string that, when set, is prepended to the player's name in chat messages. Does not affect the name tag above the player's head or the player list - use Entity.nameTag for that. To prefix the message text itself, use Player.chatMessagePrefix. Set to undefined to clear.

#chatNameSuffix?

optional chatNameSuffix?: string

Beta World Mutation

#Remarks

一个可选的字符串，设置后会被追加到聊天消息中玩家的名称之后。不影响玩家头顶的名称标签或玩家列表 —— 请使用 Entity.nameTag 设置。另请参见 Player.chatNamePrefix。设置为 undefined 以清除。

An optional string that, when set, is appended to the player's name in chat messages. Does not affect the name tag above the player's head or the player list - use Entity.nameTag for that. See also Player.chatNamePrefix. Set to undefined to clear.

#clientSystemInfo

readonly clientSystemInfo: ClientSystemInfo

Beta

#Remarks

包含玩家的设备信息。

Contains the player's device information.

#Throws

This property can throw when used.

#commandPermissionLevel

commandPermissionLevel: CommandPermissionLevel

World Mutation Beta

#Remarks

#dimension

readonly dimension: Dimension

Beta

#Remarks

实体当前所在的维度。

Dimension that the entity is currently within.

#Throws

This property can throw when used.

EngineError

InvalidEntityError

#Inherited from

Entity.dimension

#fogSettings

readonly fogSettings: FogSettings

Beta

#Remarks

包含用于操作玩家的渲染距离迷雾设置的方法。

Contains methods for manipulating the render distance fog settings of a Player.

#graphicsMode

readonly graphicsMode: GraphicsMode

Beta

#Remarks

获取玩家客户端的当前图形模式。这可以在设置菜单的视频部分中更改，具体取决于可用硬件。

Gets the current graphics mode of the player's client. This can be changed in the Video section of the settings menu based on what hardware is available.

#Throws

This property can throw when used.

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.

#Inherited from

Entity.id

#inputInfo

readonly inputInfo: InputInfo

Beta

#Remarks

包含玩家的输入信息。

Contains the player's input information.

#inputPermissions

readonly inputPermissions: PlayerInputPermissions

Beta

#Remarks

玩家的输入权限。

Input permissions of the player.

#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

#Inherited from

Entity.isClimbing

#isEmoting

readonly isEmoting: boolean

Beta

#Remarks

如果为 true，玩家当前正在进行表情动作。

If true, the player is currently emoting.

#Throws

This property can throw when used.

#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

#Inherited from

Entity.isFalling

#isFlying

readonly isFlying: boolean

Beta

#Remarks

玩家是否在飞行。例如，在创造模式或旁观者模式下。

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

#Throws

This property can throw when used.

#isGliding

readonly isGliding: boolean

Beta

#Remarks

玩家是否正在使用鞘翅滑翔。

Whether the player is gliding with Elytra.

#Throws

This property can throw when used.

#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

#Inherited from

Entity.isInWater

#isJumping

readonly isJumping: boolean

Beta

#Remarks

玩家是否正在跳跃。玩家按住跳跃动作时，此值将保持为 true。

Whether the player is jumping. This will remain true while the player is holding the jump action.

#Throws

This property can throw when used.

#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

#Inherited from

Entity.isOnGround

#isSleeping

readonly isSleeping: boolean

Beta

#Remarks

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

If true, the entity is currently sleeping.

#Throws

This property can throw when used.

InvalidEntityError

#Inherited from

Entity.isSleeping

#isSneaking

isSneaking: boolean

World Mutation Beta

#Remarks

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

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

#Inherited from

Entity.isSneaking

#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

#Inherited from

Entity.isSprinting

#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

#Inherited from

Entity.isSwimming

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

#Inherited from

Entity.isValid

#level

readonly level: number

Beta

#Remarks

玩家当前的总等级，基于其经验值。

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

#Throws

This property can throw when used.

#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

#Inherited from

Entity.localizationKey

#location

readonly location: Vector3

Beta

#Remarks

实体的当前位置。

Current location of the entity.

#Throws

This property can throw when used.

InvalidEntityError

#Inherited from

Entity.location

#locatorBar

readonly locatorBar: LocatorBar

Beta

#Remarks

玩家的 Locator Bar 定位栏。此属性用于管理显示在 HUD 上的导航点。

The player's Locator Bar. This property is used for managing waypoints displayed on the HUD.

#name

readonly name: string

Beta

#Remarks

玩家的名称。

Name of the player.

#Throws

This property can throw when used.

#nameplateDepthTested

nameplateDepthTested: boolean

World Mutation Beta

#Remarks

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

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

#Inherited from

Entity.nameplateDepthTested

#nameplateRenderDistance

nameplateRenderDistance: number

World Mutation Beta

#Remarks

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

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

#Inherited from

Entity.nameplateRenderDistance

#nameTag

nameTag: string

World Mutation Beta

#Remarks

实体的给定名称。

Given name of the entity.

#Inherited from

Entity.nameTag

#onScreenDisplay

readonly onScreenDisplay: ScreenDisplay

Beta

#Remarks

包含用于操作玩家的屏幕显示的方法。

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

#Throws

This property can throw when used.

#persistentId

readonly persistentId: string

Beta

#Remarks

一个可用于跨会话标识玩家的标识符。

An identifier that can be used to identify a player across sessions.

#Throws

This property can throw when used.

EngineError

InvalidEntityError

#playerPermissionLevel

readonly playerPermissionLevel: PlayerPermissionLevel

Beta

#Throws

This property can throw when used.

InvalidEntityError

#scoreboardIdentity?

readonly optional scoreboardIdentity?: ScoreboardIdentity

Beta

#Remarks

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

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

#Inherited from

Entity.scoreboardIdentity

#selectedSlotIndex

selectedSlotIndex: number

World Mutation Beta

#Remarks

#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

#Inherited from

Entity.target

#totalXpNeededForNextLevel

readonly totalXpNeededForNextLevel: number

Beta

#Remarks

玩家达到下一级所需的总经验值。

The overall total set of experience needed to achieve the next level for a player.

#Throws

This property can throw when used.

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

#Inherited from

Entity.typeId

#xpEarnedAtCurrentLevel

readonly xpEarnedAtCurrentLevel: number

Beta

#Remarks

玩家当前等级已获得的经验值。

The current set of experience achieved for the player.

#Throws

This property can throw when used.

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

#Inherited from

Entity.addEffect

#addExperience()

addExperience(amount): number

World Mutation Beta

#Parameters

#amount

number

要添加的经验值数量。注意，这可以为负值。最小/最大边界为 -2^24 ~ 2^24。

Amount of experience to add. Note that this can be negative. Min/max bounds at -2^24 ~ 2^24 Bounds: [-16777216, 16777216]

#Returns

number

返回玩家的当前经验值。

Returns the current experience of the Player.

#Remarks

向玩家添加/移除经验值，并返回玩家的当前经验值。

Adds/removes experience to/from the Player and returns the current experience of the Player.

#Throws

This function can throw errors.

#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

#Inherited from

Entity.addItem

#addLevels()

addLevels(amount): number

World Mutation Beta

#Parameters

#amount

number

要添加到玩家的数量。最小/最大边界为 -2^24 ~ 2^24。

Amount to add to the player. Min/max bounds at -2^24 ~ 2^24 Bounds: [-16777216, 16777216]

#Returns

number

返回玩家的当前等级。

Returns the current level of the Player.

#Remarks

向玩家添加/移除等级，并返回玩家的当前等级。

Adds/removes level to/from the Player and returns the current level of the Player.

#Throws

This function can throw errors.

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

#Inherited from

Entity.addTag

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

#Inherited from

Entity.applyDamage

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

#Inherited from

Entity.applyImpulse

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

#Inherited from

Entity.applyKnockback

#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

#Inherited from

Entity.clearDynamicProperties

#clearPropertyOverridesForEntity()

clearPropertyOverridesForEntity(targetEntity): void

World Mutation Beta

#Parameters

#targetEntity

string | Entity

正在清除 Entity 属性覆盖的实体或实体 ID。

The Entity or the ID of the Entity whose Entity Property overrides are being cleared.

#Returns

void

#Remarks

对此玩家，移除目标实体上所有 Entity 属性的覆盖。此更改不会应用到其他玩家，且直到下一刻才会应用。

For this player, removes all overrides of any Entity Properties on the target Entity. This change is not applied until the next tick and will not apply to other players.

#Throws

如果实体或实体 ID 无效则抛出。

Throws if the Entity or Entity ID is invalid.

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

#Inherited from

Entity.clearVelocity

#eatItem()

eatItem(itemStack): void

Beta World Mutation

#Parameters

#itemStack

ItemStack

要吃的物品。

The item to eat.

#Returns

void

#Remarks

吃掉一个物品，为玩家提供该物品的饥饿度和饱和度效果。只能对食物物品使用。

Eats an item, providing the item's hunger and saturation effects to the player. Can only be used on food items.

#Throws

如果物品不是食物物品则抛出。

Throws if the item is not a food item.

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

#Inherited from

Entity.extinguishFire

#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

#Inherited from

Entity.getAABB

#getAimAssist()

getAimAssist(): PlayerAimAssist

Beta

#Returns

PlayerAimAssist

#Remarks

玩家的瞄准辅助设置。

The player's aim-assist settings.

#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

#Inherited from

Entity.getAllBlocksStandingOn

#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

#Inherited from

Entity.getBlockFromViewDirection

#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

#Inherited from

Entity.getBlockStandingOn

#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

#Inherited from

Entity.getComponent

#getComponents()

getComponents(): EntityComponent[]

Beta

#Returns

EntityComponent[]

#Remarks

返回此实体上存在的所有脚本组件。

Returns all scripting components that are present on this entity.

#Throws

This function can throw errors.

InvalidEntityError

#Inherited from

Entity.getComponents

#getControlScheme()

getControlScheme(): ControlScheme

Beta

#Returns

ControlScheme

#Remarks

返回玩家当前的控制方案。

Returns the player's current control scheme.

#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

#Inherited from

Entity.getDynamicProperty

#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

#Inherited from

Entity.getDynamicPropertyIds

#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

#Inherited from

Entity.getDynamicPropertyTotalByteCount

#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

#Inherited from

Entity.getEffect

#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

#Inherited from

Entity.getEffects

#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

#Inherited from

Entity.getEntitiesFromViewDirection

#getGameMode()

getGameMode(): GameMode

Beta

#Returns

GameMode

#Remarks

获取此玩家的活跃游戏模式（如果已指定）。

Retrieves the active gamemode for this player, if specified.

#Throws

This function can throw errors.

#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

#Inherited from

Entity.getHeadLocation

#getItemCooldown()

getItemCooldown(cooldownCategory): number

Beta

#Parameters

#cooldownCategory

string

指定要获取当前冷却时间的冷却类别。

Specifies the cooldown category to retrieve the current cooldown for.

#Returns

number

#Remarks

获取特定冷却类别的当前物品冷却时间。

Gets the current item cooldown time for a particular cooldown category.

#Throws

This function can throw errors.

#getPing()

getPing(): number

Beta

#Returns

number

玩家的延迟（以毫秒为单位）。

The player's ping in milliseconds.

#Remarks

获取玩家的延迟（以毫秒为单位）。

Gets the player's ping in milliseconds.

#Throws

This function can throw errors.

EngineError

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

#Inherited from

Entity.getProperty

#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

#Inherited from

Entity.getRotation

#getSpawnPoint()

getSpawnPoint(): DimensionLocation | undefined

Beta

#Returns

DimensionLocation | undefined

#Remarks

获取玩家的当前出生点。

Gets the current spawn point of the player.

#Throws

This function can throw errors.

#getSplitScreenSlot()

getSplitScreenSlot(): PlayerSplitScreenSlot | undefined

Beta

#Returns

PlayerSplitScreenSlot | undefined

玩家的分屏槽位，如果玩家不在分屏会话中则返回 undefined。

The split screen slot of the player or undefined if the player is not in a split screen session.

#Remarks

返回玩家的分屏槽位。

Returns the split screen slot of the player.

#Throws

This function can throw errors.

EngineError

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

#Inherited from

Entity.getTags

#getTotalXp()

getTotalXp(): number

Beta

#Returns

number

#Remarks

获取玩家的总经验值。

Gets the total experience of the Player.

#Throws

This function can throw errors.

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

#Inherited from

Entity.getVelocity

#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

#Inherited from

Entity.getViewDirection

#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

#Inherited from

Entity.hasComponent

#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

#Inherited from

Entity.hasTag

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

#Inherited from

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

#Inherited from

Entity.lookAt

#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

#Inherited from

Entity.matches

#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

#Inherited from

Entity.playAnimation

#playMusic()

playMusic(trackId, musicOptions?): void

World Mutation Beta

#Parameters

#trackId

string

要播放的音乐曲目标识符。

Identifier of the music track to play.

#musicOptions?

MusicOptions

音乐曲目的附加选项。

Additional options for the music track.

#Returns

void

#Remarks

播放只有此特定玩家能听到的音乐曲目。

Plays a music track that only this particular player can hear.

#Throws

This function can throw errors.

#playSound()

playSound(soundId, soundOptions?): SoundInstance

World Mutation Beta

#Parameters

#soundId

string | SoundDefinition

#soundOptions?

PlayerSoundOptions

音效的附加可选选项。

Additional optional options for the sound.

#Returns

SoundInstance

#Remarks

播放只有此特定玩家能听到的音效。

Plays a sound that only this particular player can hear.

#Throws

This function can throw errors.

EngineError

Error

#Example

playMusicAndSound.ts

import { world, MusicOptions, WorldSoundOptions, PlayerSoundOptions, DimensionLocation } from '@minecraft/server';

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

  const musicOptions: MusicOptions = {
    fade: 0.5,
    loop: true,
    volume: 1.0,
  };
  world.playMusic('music.menu', musicOptions);

  const worldSoundOptions: WorldSoundOptions = {
    pitch: 0.5,
    volume: 4.0,
  };
  world.playSound('ambient.weather.thunder', targetLocation, worldSoundOptions);

  const playerSoundOptions: PlayerSoundOptions = {
    pitch: 1.0,
    volume: 1.0,
  };

  players[0].playSound('bucket.fill_water', playerSoundOptions);
}

#postClientMessage()

postClientMessage(id, value): void

Beta World Mutation

#Parameters

#id

string

#value

string

#Returns

void

#Remarks

这是一个内部方法，用于向下游客户端发布系统消息。

This is an internal-facing method for posting a system message to downstream clients.

#Throws

This function can throw errors.

#queueMusic()

queueMusic(trackId, musicOptions?): void

World Mutation Beta

#Parameters

#trackId

string

要播放的音乐曲目标识符。

Identifier of the music track to play.

#musicOptions?

MusicOptions

音乐曲目的附加选项。

Additional options for the music track.

#Returns

void

#Remarks

排队一首只有此特定玩家能听到的附加音乐曲目。如果当前没有曲目在播放，则会播放一首音乐曲目。

Queues an additional music track that only this particular player can hear. If a track is not playing, a music track will play.

#Throws

如果音量小于 0.0 将抛出错误。 如果淡变小于 0.0 将抛出错误。

An error will be thrown if volume is less than 0.0. An error will be thrown if fade is less than 0.0.

#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

#Inherited from

Entity.remove

#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

#Inherited from

Entity.removeEffect

#removePropertyOverrideForEntity()

removePropertyOverrideForEntity(targetEntity, identifier): void

World Mutation Beta

#Parameters

#targetEntity

Entity

正在移除 Entity 属性覆盖的实体。

The Entity whose Entity Property override is being removed.

#identifier

string

Entity 属性标识符。

The Entity Property identifier.

#Returns

void

#Remarks

对此玩家，移除 Entity 属性上的覆盖。此更改不会应用到其他玩家，且直到下一刻才会应用。

For this player, removes the override on an Entity Property. This change is not applied until the next tick and will not apply to other players.

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

#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

#Inherited from

Entity.removeTag

#resetLevel()

resetLevel(): void

World Mutation Beta

#Returns

void

#Remarks

重置玩家的等级。

Resets the level of the player.

#Throws

This function can throw errors.

#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

#Inherited from

Entity.resetProperty

#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

#Inherited from

Entity.runCommand

#sendMessage()

sendMessage(message): void

Beta

#Parameters

#message

string | RawMessage | (string | RawMessage)[]

要显示的消息。

The message to be displayed.

#Returns

void

#Remarks

向玩家发送消息。

Sends a message to the player.

#Throws

如果提供的 RawMessage 格式无效，此方法可能抛出错误。例如，如果为 score 提供了空的 name 字符串。

This method can throw if the provided RawMessage is in an invalid format. For example, if an empty name string is provided to score.

InvalidEntityError

RawMessageError

#Examples

nestedTranslation.ts

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

function nestedTranslation(targetLocation: DimensionLocation) {
  // Displays "Apple or Coal"
  const rawMessage = {
    translate: 'accessibility.list.or.two',
    with: { rawtext: [{ translate: 'item.apple.name' }, { translate: 'item.coal.name' }] },
  };
  world.sendMessage(rawMessage);
}

scoreWildcard.ts

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

function scoreWildcard(targetLocation: DimensionLocation) {
  // Displays the player's score for objective "obj". Each player will see their own score.
  const rawMessage = { score: { name: '*', objective: 'obj' } };
  world.sendMessage(rawMessage);
}

sendBasicMessage.ts

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

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

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

sendPlayerMessages.ts

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

function sendPlayerMessages(targetLocation: DimensionLocation) {
  for (const player of world.getAllPlayers()) {
    // Displays "First or Second"
    const rawMessage = { translate: 'accessibility.list.or.two', with: ['First', 'Second'] };
    player.sendMessage(rawMessage);

    // Displays "Hello, world!"
    player.sendMessage('Hello, world!');

    // Displays "Welcome, Amazing Player 1!"
    player.sendMessage({ translate: 'authentication.welcome', with: ['Amazing Player 1'] });

    // Displays the player's score for objective "obj". Each player will see their own score.
    const rawMessageWithScore = { score: { name: '*', objective: 'obj' } };
    player.sendMessage(rawMessageWithScore);

    // Displays "Apple or Coal"
    const rawMessageWithNestedTranslations = {
      translate: 'accessibility.list.or.two',
      with: { rawtext: [{ translate: 'item.apple.name' }, { translate: 'item.coal.name' }] },
    };
    player.sendMessage(rawMessageWithNestedTranslations);
  }
}

sendTranslatedMessage.ts

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

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

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

#setControlScheme()

setControlScheme(controlScheme?): void

World Mutation Beta

#Parameters

#controlScheme?

ControlScheme

控制方案类型。如果此参数为 undefined，此方法将清除玩家的控制方案，恢复为玩家摄像机的默认控制方案。

Control scheme type. If this argument is undefined, this method will clear the player's control scheme back to the player camera's default control scheme.

#Returns

void

如果控制方案已成功添加或更新，则不返回任何内容。如果控制方案不被玩家当前摄像机允许，则可能抛出 InvalidArgumentError。

Returns nothing if the control scheme was added or updated successfully. This can throw an InvalidArgumentError if the control scheme is not allowed by the player's current camera.

#Remarks

设置玩家的控制方案。玩家的活跃摄像机预设必须通过脚本（如 camera.setCamera()）或命令设置。

Set a player's control scheme. The player's active camera preset must be set by scripts like with camera.setCamera() or commands.

#Throws

This function can throw errors.

EngineError

InvalidArgumentError

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

#Inherited from

Entity.setDynamicProperties

#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

#Inherited from

Entity.setDynamicProperty

#setGameMode()

setGameMode(gameMode?): void

World Mutation Beta

#Parameters

#gameMode?

GameMode

活跃的游戏模式。

Active gamemode.

#Returns

void

#Remarks

为此玩家设置游戏模式覆盖。

Sets a gamemode override for this player.

#Throws

This function can throw errors.

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

#Inherited from

Entity.setOnFire

#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

#Inherited from

Entity.setProperty

#setPropertyOverrideForEntity()

setPropertyOverrideForEntity(targetEntity, identifier, value): void

World Mutation Beta

#Parameters

#targetEntity

Entity

其 Entity 属性正在被覆盖的实体。

The Entity whose Entity Property is being overriden.

#identifier

string

Entity 属性标识符。

The Entity Property identifier.

#value

string | number | boolean

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

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

#Returns

void

#Remarks

对此玩家，将目标实体上的 Entity 属性覆盖为提供的值。此属性必须是客户端同步的。此更改不会应用到其他玩家，且直到下一刻才会应用。

For this player, overrides an Entity Property on the target Entity to the provided value. This property must be client synced. This change is not applied until the next tick and will not apply to other players.

#Throws

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

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)

#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

#Inherited from

Entity.setRotation

#setSpawnPoint()

setSpawnPoint(spawnPoint?): void

World Mutation Beta

#Parameters

#spawnPoint?

DimensionLocation

#Returns

void

#Remarks

为此特定玩家设置当前起始出生点。

Sets the current starting spawn point for this particular player.

#Throws

This function can throw errors.

Error

LocationOutOfWorldBoundariesError

#spawnParticle()

spawnParticle(effectName, location, molangVariables?): void

World Mutation Beta

#Parameters

#effectName

string

要创建的粒子标识符。

Identifier of the particle to create.

#location

Vector3

创建粒子发射器的位置。

The location at which to create the particle emitter.

#molangVariables?

MolangVariableMap

一组可选的、可自定义的变量，可为该粒子进行调整。

A set of optional, customizable variables that can be adjusted for this particle.

#Returns

void

#Remarks

在世界中的指定位置创建一个新的粒子发射器。仅对目标玩家可见。

Creates a new particle emitter at a specified location in the world. Only visible to the target player.

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#Example

spawnParticle.ts

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

world.afterEvents.playerSpawn.subscribe(event => {
  const targetLocation = event.player.location;
  for (let i = 0; i < 100; i++) {
    const molang = new MolangVariableMap();

    molang.setColorRGB('variable.color', {
      red: Math.random(),
      green: Math.random(),
      blue: Math.random(),
    });

    const newLocation: Vector3 = {
      x: targetLocation.x + Math.floor(Math.random() * 8) - 4,
      y: targetLocation.y + Math.floor(Math.random() * 8) - 4,
      z: targetLocation.z + Math.floor(Math.random() * 8) - 4,
    };
    event.player.spawnParticle('minecraft:colored_flame_particle', newLocation, molang);
  }
});

#startItemCooldown()

startItemCooldown(cooldownCategory, tickDuration): void

World Mutation Beta

#Parameters

#cooldownCategory

string

指定要获取当前冷却时间的冷却类别。

Specifies the cooldown category to retrieve the current cooldown for.

#tickDuration

number

物品冷却的持续时间（以刻为单位）。

Duration in ticks of the item cooldown. Bounds: [0, 32767]

#Returns

void

#Remarks

设置特定冷却类别的物品冷却时间。

Sets the item cooldown time for a particular cooldown category.

#Throws

This function can throw errors.

#stopAllSounds()

stopAllSounds(): void

Beta World Mutation

#Returns

void

#Remarks

为此特定玩家停止所有音效播放。

Stops all sounds from playing for this particular player.

#Throws

This function can throw errors.

InvalidEntityError

#stopMusic()

stopMusic(): void

World Mutation Beta

#Returns

void

#Remarks

为此特定玩家停止播放任何音乐曲目。

Stops any music tracks from playing for this particular player.

#Throws

This function can throw errors.

#stopSound()

stopSound(soundId): void

Beta World Mutation

#Parameters

#soundId

string

音效的标识符。

Identifier of the sound.

#Returns

void

#Remarks

为此特定玩家停止播放音效。

Stops a sound from playing for this particular player.

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

#Inherited from

Entity.teleport

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

#Inherited from

Entity.triggerEvent

#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

#Inherited from

Entity.tryTeleport

#同领域相关

• BlockComponentPlayerBreakEvent
• BlockComponentPlayerInteractEvent
• BlockComponentPlayerPlaceBeforeEvent
• BlockRecordPlayerComponent
• KilledByPlayerCondition
• KilledByPlayerOrPetsCondition