实体-Entity

表示世界中一个实体的状态（可以是生物、玩家或其他移动物体如矿车）

参考链接：微软文档 Entity

属性

id

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

Details

类型：

str

示例：

entity_id = entity.id

isValid

只读实体是否有效（存活）

Details

类型：

bool

示例：

if entity.isValid:
    print("实体存活")

dimension

只读实体当前所在的维度

Details

类型：

Dimension

示例：

dim = entity.dimension

isClimbing

只读实体是否正在攀爬（例如玩家在梯子旁或蜘蛛在石墙旁）

Details

类型：

bool

示例：

if entity.isClimbing:
    print("实体正在攀爬")

isFalling

只读实体是否正在下落（下落距离大于0，或滑翔时大于1）

Details

类型：

bool

示例：

if entity.isFalling:
    print("实体正在下落")

isInWater

只读实体任何部分是否在水块中

Details

类型：

bool

示例：

if entity.isInWater:
    print("实体在水中")

isOnGround

只读实体是否在固体方块上。此属性可能以意外的方式表现。当实体首次生成时，此属性将始终为 true，如果实体没有重力，此属性可能不正确。

Details

类型：

bool

示例：

if entity.isOnGround:
    print("实体在地面上")

isSleeping

只读实体是否正在睡觉

Details

类型：

bool

示例：

if entity.isSleeping:
    print("实体在睡觉")

isSitting

只读实体是否正在坐下

Details

类型：

bool

示例：

if entity.isSitting:
    print("实体在坐下")

isSneaking

只读实体是否正在潜行（移动更慢更安静）

Details

类型：

bool

示例：

if entity.isSneaking:
    print("实体在潜行")

isSprinting

只读实体是否正在冲刺（例如玩家使用冲刺动作，豹猫逃跑或猪使用胡萝卜钓竿加速）

Details

类型：

bool

示例：

if entity.isSprinting:
    print("实体在冲刺")

isSwimming

只读实体是否处于游泳状态（例如玩家使用游泳动作或水中的鱼）

Details

类型：

bool

示例：

if entity.isSwimming:
    print("实体在游泳")

location

只读实体的当前位置

Details

类型：

Vector3

示例：

pos = entity.location
print(f"实体位置: {pos.x}, {pos.y}, {pos.z}")

nameTag

实体的名称标签

Details

类型：

str

示例：

# 获取名称
name = entity.nameTag

# 设置名称
entity.nameTag = "新名称"

health

实体的生命值

Details

类型：

float

示例：

# 获取生命值
hp = entity.health

# 设置生命值
entity.health = 20.0

typeId

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

Details

类型：

str

示例：

entity_type = entity.typeId

方法

addEffect

添加或更新实体上的效果（如中毒）

Details

addEffect(effectType, duration, options=EntityEffectOptions)

参数：

effectType
- 效果类型
- 类型：str | EffectType
duration
- 持续时间（刻）
- 类型：int
options
- 效果选项
- 类型：EntityEffectOptions | dict

返回值类型：

Effect

示例：

entity.addEffect("poison", 100, {"amplifier": 1})

addTag

向实体添加指定标签

Details

addTag(tag)

参数：

tag
- 要添加的标签
- 类型：str

返回值类型：

bool

示例：

success = entity.addTag("my_tag")

applyDamage

对实体造成伤害

Details

applyDamage(amount, options=None)

参数：

amount
- 伤害量
- 类型：int
options
- 伤害选项
- 类型：dict | EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions

返回值类型：

bool

示例：

entity.applyDamage(10, {"cause": "entity_attack"})

applyImpulse

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

Details

applyImpulse(vector)

参数：

vector
- 冲量向量
- 类型：Vector3 | dict

无返回值

示例：

entity.applyImpulse({"x": 0, "y": 1, "z": 0})

applyKnockback

向实体施加击退效果

Details

applyKnockback(horizontalForce, verticalStrength)

参数：

horizontalForce
- 水平击退力
- 类型：dict | VectorXZ
verticalStrength
- 垂直击退强度
- 类型：float

无返回值

示例：

entity.applyKnockback({"x": 1, "z": 0}, 0.5)

clearDynamicProperties

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

Details

clearDynamicProperties()

无返回值

示例：

entity.clearDynamicProperties()

clearVelocity

将实体的当前速度设置为零。注意此方法可能对玩家没有影响。

Details

clearVelocity()

无返回值

示例：

entity.clearVelocity()

extinguishFire

如果实体着火，则熄灭火焰

Details

extinguishFire(useEffects=True)

参数：

useEffects
- 是否显示与熄灭相关的视觉效果
- 类型：bool

返回值类型：

bool

示例：

success = entity.extinguishFire()

getBlockFromViewDirection

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

Details

getBlockFromViewDirection(options=BlockRaycastOptions)

参数：

options
- 射线投射选项
- 类型：dict | BlockRaycastOptions

返回值类型：

BlockRaycastHit

示例：

hit = entity.getBlockFromViewDirection()
if hit:
    print(f"看向的方块: {hit.block}")

getComponent

获取实体的组件（表示额外能力）

Details

getComponent(componentId)

参数：

componentId
- 组件ID
- 类型：str

返回值类型：

EntityComponent | None

示例：

component = entity.getComponent("minecraft:health")

getComponents

返回此实体上存在且受API支持的所有组件

Details

getComponents()

返回值类型：

list[EntityComponent]

示例：

components = entity.getComponents()

getDynamicProperty

返回属性值

Details

getDynamicProperty(identifier)

参数：

identifier
- 属性标识符
- 类型：str

返回值类型：

Any | None

示例：

value = entity.getDynamicProperty("custom_data")

getDynamicPropertyIds

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

Details

getDynamicPropertyIds()

返回值类型：

list[str]

示例：

property_ids = entity.getDynamicPropertyIds()

getEffect

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

Details

getEffect(effectType)

参数：

effectType
- 效果类型
- 类型：str | EffectType

返回值类型：

Effect

示例：

effect = entity.getEffect("poison")

getEffects

返回应用于此实体的一组效果

Details

getEffects()

返回值类型：

list[Effect]

示例：

effects = entity.getEffects()

getEntitiesFromViewDirection

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

Details

getEntitiesFromViewDirection(options=EntityRaycastOptions)

参数：

options
- 实体射线投射选项
- 类型：dict

返回值类型：

list[EntityRaycastHit]

示例：

hits = entity.getEntitiesFromViewDirection()
for hit in hits:
    print(f"看到的实体: {hit.entity}")

getHeadLocation

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

Details

getHeadLocation()

返回值类型：

Vector3

示例：

head_pos = entity.getHeadLocation()

getRotation

返回此实体的当前旋转组件

Details

getRotation()

返回值类型：

Vector2

示例：

rotation = entity.getRotation()

getTags

返回与实体关联的所有标签

Details

getTags()

返回值类型：

list[str]

示例：

tags = entity.getTags()

getVelocity

返回实体的当前速度向量

Details

getVelocity()

返回值类型：

Vector3

示例：

velocity = entity.getVelocity()

getViewDirection

返回实体的当前视线方向

Details

getViewDirection()

返回值类型：

Vector3

示例：

direction = entity.getViewDirection()

hasComponent

返回指定组件是否存在于此实体上

Details

hasComponent(componentId)

参数：

componentId
- 组件ID
- 类型：str

返回值类型：

bool

示例：

has_health = entity.hasComponent("minecraft:health")

hasTag

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

Details

hasTag(tag)

参数：

tag
- 要检查的标签
- 类型：str

返回值类型：

bool

示例：

has_tag = entity.hasTag("my_tag")

kill

杀死此实体。实体将正常掉落战利品。

Details

kill()

返回值类型：

bool

示例：

success = entity.kill()

removeEffect

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

Details

removeEffect(effectType)

参数：

effectType
- 效果类型
- 类型：str | EffectType

返回值类型：

bool

示例：

success = entity.removeEffect("poison")

removeTag

从实体移除指定标签

Details

removeTag(tag)

参数：

tag
- 要移除的标签
- 类型：str

返回值类型：

bool

示例：

success = entity.removeTag("my_tag")

runCommand

在实体上运行同步命令

Details

runCommand(commandString)

参数：

commandString
- 要执行的命令
- 类型：str

返回值类型：

CommandResult

示例：

result = entity.runCommand("say hello")

setDynamicProperty

将指定属性设置为值

Details

setDynamicProperty(identifier, value)

参数：

identifier
- 属性标识符
- 类型：str
value
- 要设置的值
- 类型：Any

无返回值

示例：

entity.setDynamicProperty("custom_data", 123)

teleport

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

Details

teleport(location, teleportOptions=None)

参数：

location
- 目标位置
- 类型：Vector3 | dict
teleportOptions
- 传送选项
- 类型：dict | TeleportOptions

无返回值

示例：

entity.teleport({"x": 100, "y": 64, "z": 200})

属性​

id​

类型：​

示例：​

isValid​

类型：​

示例：​

dimension​

类型：​

示例：​

isClimbing​

类型：​

示例：​

isFalling​

类型：​

示例：​

isInWater​

类型：​

示例：​

isOnGround​

类型：​

示例：​

isSleeping​

类型：​

示例：​

isSitting​

类型：​

示例：​

isSneaking​

类型：​

示例：​

isSprinting​

类型：​

示例：​

isSwimming​

类型：​

示例：​

location​

类型：​

示例：​

nameTag​

类型：​

示例：​

health​

类型：​

示例：​

typeId​

类型：​

示例：​

方法​

addEffect​

参数：​

返回值类型：​

示例：​

addTag​

参数：​

返回值类型：​

示例：​

applyDamage​

参数：​

返回值类型：​

示例：​

applyImpulse​

参数：​

无返回值​

示例：​

applyKnockback​

参数：​

无返回值​

示例：​

clearDynamicProperties​

无返回值​

示例：​

clearVelocity​

无返回值​

示例：​

extinguishFire​

参数：​

返回值类型：​

示例：​

属性

id

类型：

示例：

isValid

类型：

示例：

dimension

类型：

示例：

isClimbing

类型：

示例：

isFalling

类型：

示例：

isInWater

类型：

示例：

isOnGround

类型：

示例：

isSleeping

类型：

示例：

isSitting

类型：

示例：

isSneaking

类型：

示例：

isSprinting

类型：

示例：

isSwimming

类型：

示例：

location

类型：

示例：

nameTag

类型：

示例：

health

类型：

示例：

typeId

类型：

示例：

方法

addEffect

参数：

返回值类型：

示例：

addTag

参数：

返回值类型：

示例：

applyDamage

参数：

返回值类型：

示例：

applyImpulse

参数：

无返回值

示例：

applyKnockback

参数：

无返回值

示例：

clearDynamicProperties

无返回值

示例：

clearVelocity

无返回值

示例：

extinguishFire

参数：

返回值类型：

示例：