跳到正文
本頁目錄

🎈 實體對象 API

在腳本引擎中,使用「實體對象」來操作和獲取某一個實體的相關信息。

獲取一個實體對象

從事件或API獲取

通過註冊事件監聽函數,或者調用某些返回實體對象的函數,來獲取到BDS給出的實體對象
詳見 事件監聽文檔 - EventAPI

獲取當前所有已加載的實體

此函數會返回一個實體對象的數組,其中每個對象都對應了一個已加載的實體

mc.getAllEntities()

  • 返回值:實體對象列表
  • 返回值類型:Array<Entity,Entity,...>

獲取在特定範圍內的實體

mc.getEntities(startPos[,range])
mc.getEntities(startPos,endPos[,range])

  • 參數:
    • startPos : IntPos / FloatPos
      搜索的起始座標
    • endPos : IntPos / FloatPos
      搜索的終止座標
    • range : Number
      搜索範圍
  • 返回值: 實體對象列表
  • 返回值類型: Array<Entity,Entity,...>

從現有實體獲取

通過實體信息手動生成實體對象
通過此函數來手動生成對象,注意,你要獲取的實體必須是在線狀態,否則會生成失敗

Warning

此函數僅在0.9.5及以後版本可用

mc.getEntity(info)

  • 參數:
    • info : Number
      實體的UniqueId或者RuntimeId
  • 返回值:生成的實體對象
  • 返回值類型:Entity
    • 如返回值為 Null 則表示獲取實體失敗

生成新生物並獲取

通過此函數,在指定的位置生成一個新生物,並獲取它對應的實體對象

mc.spawnMob(name,pos)
mc.spawnMob(name,x,y,z,dimid)

  • 參數:
    • name : String
      生物的命名空間名稱,如 minecraft:creeper
    • pos : IntPos/ FloatPos
      生成生物的位置的座標對象(或者使用x, y, z, dimid來確定生成位置)
  • 返回值:生成的實體對象
  • 返回值類型:Entity
    • 如返回值為 Null 則表示生成失敗

注意:不要長期保存一個實體對象
當實體對象對應的實體被銷燬時,對應的實體對象將同時釋放。因此,如果有長期操作某個實體的需要,請通過上述途徑獲取實時的實體對象

召喚新生物並獲取

Warning

此函數僅在0.19.1及以後版本可用

通過此函數,在指定的位置召喚一個新生物,並獲取它對應的實體對象

mc.summonMob(name,pos[,event])
mc.summonMob(name,x,y,z,dimid[,event])

  • 參數:
    • name : String
      生物的命名空間名稱,如 minecraft:creeper
    • pos : IntPos/ FloatPos
      生成生物的位置的座標對象(或者使用x, y, z, dimid來確定生成位置)
    • event : String
      可選的初始化事件名稱
  • 返回值:生成的實體對象
  • 返回值類型:Entity
    • 如返回值為 Null 則表示生成失敗

注意:不要長期保存一個實體對象
當實體對象對應的實體被銷燬時,對應的實體對象將同時釋放。因此,如果有長期操作某個實體的需要,請通過上述途徑獲取實時的實體對象

通過NBT加載生物並獲取

Warning

此函數僅在0.19.1及以後版本可用

通過此函數,使用指定的NBT數據在指定位置生成一個生物,並獲取它對應的實體對象

mc.loadMob(nbt,pos)
mc.loadMob(nbt,x,y,z,dimid)

  • 參數:
    • nbt : NbtCompound
      生物的NBT對象
    • pos : IntPos/ FloatPos
      生成生物的位置的座標對象(或者使用x, y, z, dimid來確定生成位置)
  • 返回值:生成的實體對象
  • 返回值類型:Entity
    • 如返回值為 Null 則表示生成失敗

複製生物並獲取

通過此函數,在指定的位置複製另一個實體,並獲取它對應的實體對象

mc.cloneMob(entity,pos)
mc.cloneMob(entity,x,y,z,dimid)

  • 參數:
    • entity : Entity
      需要複製的實體對象
    • pos : IntPos/ FloatPos
      生成生物的位置的座標對象(或者使用x, y, z, dimid來確定生成位置)
  • 返回值 複製的實體對象
  • 返回值類型:Entity
    • 如返回值為 Null 則表示生成失敗

注意:不要長期保存一個實體對象
當實體對象對應的實體被銷燬時,對應的實體對象將同時釋放。因此,如果有長期操作某個實體的需要,請通過上述途徑獲取實時的實體對象

實體對象 - 屬性

每一個實體對象都包含一些固定的對象屬性。對於某個特定的實體對象en,有以下這些屬性

屬性 含義 類型
en.name 實體名稱 String
en.type 實體標準類型名 String
en.id 實體的遊戲內 id Integer
en.pos 實體所在座標 FloatPos
en.feetPos 實體腿部所在座標 FloatPos
en.blockPos 實體所在的方塊座標 IntPos
en.maxHealth 實體最大生命值 Integer
en.health 實體當前生命值 Integer
en.canFly 實體是否能飛行 Boolean
en.canFreeze 實體是否能被凍結 Boolean
en.canSeeDaylight 實體是否能看到天空 Boolean
en.canPickupItems 實體是否能拾取物品 Boolean
en.inAir 實體是否懸空 Boolean
en.inWater 實體是否在水中 Boolean
en.inLava 實體是否在岩漿中 Boolean
en.inRain 實體是否在雨中 Boolean
en.inSnow 實體是否在雪中 Boolean
en.inWall 實體是否在牆上 Boolean
en.inWaterOrRain 實體是否在水中或雨中 Boolean
en.inWorld 實體是否在世界中 Boolean
en.speed 實體當前速度 Float
en.direction 實體當前朝向 DirectionAngle
en.uniqueId 實體唯一標識符 String
en.runtimeId 實體運行時標識符(在 0.9.5 時被加入) String
en.isInvisible 實體是否不可見 Boolean
en.isInsidePortal 實體是否在門戶內 Boolean
en.isTrusting 實體是否信任 Boolean
en.isTouchingDamageBlock 實體是否接觸到傷害方塊 Boolean
en.isOnFire 實體是否著火 Boolean
en.isOnGround 實體是否在地面 Boolean
en.isOnHotBlock 實體是否在熱塊上 Boolean
en.isTrading 實體是否在交易 Boolean
en.isRiding 實體是否正在騎行 Boolean
en.isDancing 實體是否在跳舞 Boolean
en.isSleeping 實體是否在睡覺 Boolean
en.isAngry 實體是否生氣 Boolean
en.isBaby 實體是否為幼體 Boolean
en.isMoving 實體是否移動 Boolean

這些對象屬性都是隻讀的,無法被修改

  • 實體當前朝向 屬性的詳細解釋見 基礎遊戲接口文檔
  • 座標 和 腿部座標:如果這個實體為兩格高,則pos與feetPos不同,pos為實體視角高度的座標,feetPos為腿部所在格子的方塊座標

實體對象 - 函數

每一個實體對象都包含一些可以執行的成員函數(成員方法)。對於某個特定的實體對象en,可以通過以下這些函數對這個實體進行一些操作

傳送實體至指定位置

en.teleport(pos[,rot])
en.teleport(x,y,z,dimid,[,rot])

  • 參數:

    • pos :IntPos/ FloatPos
      目標位置座標(或者使用x, y, z, dimid來確定實體位置)

    • rot: DirectionAngle

    (可選參數)傳送後實體的朝向,若缺省則與傳送前朝向相同 - 返回值:是否成功傳送 - 返回值類型:Boolean

殺死指定實體

en.kill()

  • 返回值:是否成功執行
  • 返回值類型:Boolean

使指定實體刷新消失

en.despawn()

  • 返回值:是否成功執行
  • 返回值類型:Boolean

移除指定實體

en.remove()

  • 返回值:是否成功執行
  • 返回值類型:Boolean

對實體造成傷害

en.hurt(damage,type,source)

  • 參數:
    • damage : Float
      對實體造成的傷害數值
    • type : Integer
      傷害類型
    • source : Entity 傷害來源
  • 返回值:是否造成傷害
  • 返回值類型:Boolean

注意,此處造成的傷害為真實傷害,無法被盔甲等保護裝備減免

ActorDamageCause 枚舉 值
ActorDamageCause.None -1
ActorDamageCause.Override 0
ActorDamageCause.Contact 1
ActorDamageCause.EntityAttack 2
ActorDamageCause.Projectile 3
ActorDamageCause.Suffocation 4
ActorDamageCause.Fall 5
ActorDamageCause.Fire 6
ActorDamageCause.FireTick 7
ActorDamageCause.Lava 8
ActorDamageCause.Drowning 9
ActorDamageCause.BlockExplosion 10
ActorDamageCause.EntityExplosion 11
ActorDamageCause.Void 12
ActorDamageCause.SelfDestruct 13
ActorDamageCause.Magic 14
ActorDamageCause.Wither 15
ActorDamageCause.Starve 16
ActorDamageCause.Anvil 17
ActorDamageCause.Thorns 18
ActorDamageCause.FallingBlock 19
ActorDamageCause.Piston 20
ActorDamageCause.FlyIntoWall 21
ActorDamageCause.Magma 22
ActorDamageCause.Fireworks 23
ActorDamageCause.Lightning 24
ActorDamageCause.Charging 25
ActorDamageCause.Temperature 26
ActorDamageCause.Freezing 27
ActorDamageCause.Stalactite 28
ActorDamageCause.Stalagmite 29
ActorDamageCause.RamAttack 30
ActorDamageCause.SonicBoom 31
ActorDamageCause.Campfire 32
ActorDamageCause.SoulCampfire 33
ActorDamageCause.MaceSmash 34
ActorDamageCause.All 35

治療實體

en.heal(health)

  • 參數:
    • health : Integer
      治療的心數
  • 返回值: 是否治療成功
  • 返回值類型: Boolean

設置實體的生命值

en.setHealth(health)

  • 參數:
    • health : Integer
      生命值數
  • 返回值: 是否成功
  • 返回值類型: Boolean

為實體設置傷害吸收屬性

en.setAbsorption(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置攻擊傷害屬性

en.setAttackDamage(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置最大攻擊傷害屬性

en.setMaxAttackDamage(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置跟隨範圍

en.setFollowRange(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置擊退抵抗屬性

en.setKnockbackResistance(value)

  • 參數:
    • value : Integer
      新的值 (0 or 1)
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置幸運屬性

en.setLuck(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置移動速度屬性

en.setMovementSpeed(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置水下移動速度屬性

en.setUnderwaterMovementSpeed(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

為實體設置岩漿上移動速度屬性

en.setLavaMovementSpeed(value)

  • 參數:
    • value : Integer
      新的值
  • 返回值: 為實體設置屬性值是否成功
  • 返回值類型: Boolean

設置實體的最大生命值

en.setMaxHealth(health)

  • 參數:
    • health : Integer
      生命值數
  • 返回值: 是否成功
  • 返回值類型: Boolean

設置特定實體為燃燒狀態

en.setFire(time, isEffect)

  • 參數:
    • time : Integer
      燃燒的時間,秒為單位
    • isEffect : Boolean
      是否有火焰效果
  • 返回值: 是否設置成功
  • 返回值類型: Boolean

熄滅實體

en.stopFire()

  • 返回值: 是否熄滅成功
  • 返回值類型: Boolean

縮放實體

en.setScale(scale)

  • 參數:
    • scale : Float
      新的實體體積
  • 返回值: 實體是否成功地被縮放
  • 返回值類型: Boolean

設置實體自定義名稱

Warning

此函數僅在0.19.1及以後版本可用

en.setCustomName(name)

  • 參數:
    • name : String 實體新的自定義名稱
  • 返回值: 是否設置成功
  • 返回值類型: Boolean

獲取實體自定義名稱

Warning

此函數僅在0.19.1及以後版本可用

en.getCustomName()

  • 返回值: 實體自定義名稱
  • 返回值類型: String

獲取實體到座標的距離

en.distanceTo(pos) en.distanceToSqr(pos)

  • 參數:
    • pos : Entity / Player / IntPos / FloatPos 目標位置
  • 返回值: 到座標的距離(方塊)
  • 返回值類型: Number

注意 若玩家的座標與目標的座標不在同一維度,將返回整數最大值。

判斷一個實體對象是不是玩家

en.isPlayer()

  • 返回值:當前實體對象是不是玩家
  • 返回值類型:Boolean

將實體對象轉換玩家對象

en.toPlayer()

  • 返回值:轉換成的玩家對象
  • 返回值類型:Player
    • 如果此實體對象指向的不是某個玩家,或者轉換失敗,則返回 Null

如果當前實體對象指向的是一個玩家,可以使用此函數將實體對象轉換為玩家對象,以使用更多的玩家相關 API

判斷一個實體對象是不是掉落物實體

en.isItemEntity()

  • 返回值:當前實體對象是不是掉落物實體
  • 返回值類型:Boolean

獲取掉落物實體中的物品對象

en.toItem()

  • 返回值:獲取到的物品對象
  • 返回值類型:Item
    • 如果此實體對象不是掉落物實體,或者獲取失敗,則返回 Null

如果當前實體對象是一個掉落物實體,可以使用此函數獲取掉落物實體中的物品對象,以使用更多的物品相關 API

獲取實體當前站立所在的方塊

en.getBlockStandingOn()

  • 返回值:當前站立在的方塊對象
  • 返回值類型:Block

獲取生物盔甲欄的容器對象

en.getArmor()

  • 返回值:此實體盔甲欄對應的容器對象
  • 返回值類型:Container

關於容器對象的更多使用,請參考 容器對象 API文檔

判斷生物是否擁有容器(盔甲欄除外)

en.hasContainer()

  • 返回值:這個生物實體是否擁有容器
  • 返回值類型:Boolean

如羊駝身上的箱子等,他們各自擁有一個屬於自己的容器對象

獲取生物所擁有的容器對象(盔甲欄除外)

en.getContainer()

  • 返回值:這個生物實體所擁有的容器對象
  • 返回值類型:Container

關於容器對象的更多使用,請參考 容器對象 API文檔

刷新生物物品欄、盔甲欄

en.refreshItems()

  • 返回值:是否成功刷新
  • 返回值類型:Boolean

在修改生物物品之後,為了促使客戶端生效,需要刷新生物所有的物品

為實體增加一個Tag

en.addTag(tag)

  • 參數:
    • tag: String
      要增加的tag字符串
  • 返回值:是否設置成功
  • 返回值類型:Boolean

為實體移除一個Tag

en.removeTag(tag)

  • 參數:
    • tag: String
      要移除的tag字符串
  • 返回值:是否移除成功
  • 返回值類型:Boolean

檢查實體是否擁有某個Tag

en.hasTag(tag)

  • 參數:
    • tag: String
      要檢查的tag字符串
  • 返回值:是否擁有這個Tag
  • 返回值類型:Boolean

返回實體擁有的所有Tag列表

en.getAllTags()

  • 返回值:實體所有的 tag 字符串列表
  • 返回值類型:Array<String,String,...>

獲取實體對應的NBT對象

en.getNbt()

  • 返回值:實體的NBT對象
  • 返回值類型:NbtCompound

寫入實體對應的NBT對象

en.setNbt(nbt)

  • 參數:
    • nbt : NbtCompound
      NBT對象
  • 返回值:是否成功寫入
  • 返回值類型:Boolean

關於NBT對象的更多使用,請參考 NBT接口文檔

獲取視線方向實體

en.getEntityFromViewVector([maxDistance])

  • 參數:
    • maxDistance : Float
      查找最大距離
  • 返回值:視線方向實體,如果獲取失敗,返回 Null
  • 返回值類型:Entity

獲取視線方向方塊

en.getBlockFromViewVector([includeLiquid,solidOnly,maxDistance,fullOnly])

  • 參數:
    • includeLiquid : Boolean
      是否包含液態方塊
    • solidOnly : Boolean
      是否僅允許 Solid 類型的方塊
    • maxDistance : Float
      查找最大距離
    • fullOnly : Boolean
      是否僅允許完整方塊
  • 返回值:視線方向方塊,如果獲取失敗,返回 Null
  • 返回值類型:Block

獲取生物所在群系ID

en.getBiomeId()

  • 返回值:群系ID
  • 返回值類型:Integer

獲取生物所在群系名稱

en.getBiomeName()

  • 返回值:群系名稱
  • 返回值類型:String

獲取實體全部藥水效果

en.getAllEffects()

  • 返回值:實體所有的藥水效果id(見下表)
  • 返回值類型:Array<Integer,Integer,...>

為實體添加一個藥水效果

en.addEffect(id, tick, level, showParticles)

  • 參數:
    • id : Number 藥水效果的id(見下表)
    • tick : Number 持續時間
    • level : Number 等級
    • showParticles : Boolean 是否顯示粒子
  • 返回值:操作是否成功
  • 返回值類型:Boolean

為實體移除一個藥水效果

en.removeEffect(id)

  • 參數:
    • id : Number 藥水效果的id(見下表)
  • 返回值:操作是否成功
  • 返回值類型:Boolean
效果 名稱 數字id
迅捷 speed 1
緩慢 slowness 2
急迫 haste 3
挖掘疲勞 mining_fatigue 4
力量 strength 5
瞬間治療 instant_health 6
瞬間傷害 instant_damage 7
跳躍提升 jump_boost 8
反胃 nausea 9
生命恢復 regeneration 10
抗性提升 resistance 11
抗火 fire_resistance 12
水下呼吸 water_breathing 13
隱身 invisibility 14
失明 blindness 15
夜視 night_vision 16
飢餓 hunger 17
虛弱 weakness 18
中毒 poison 19
凋零 wither 20
生命提升 health_boost 21
傷害吸收 absorption 22
飽和 saturation 23
飄浮 levitation 24
中毒(致命) fatal_poison 25
潮湧能量 conduit_power 26
緩降 slow_falling 27
不祥之兆 bad_omen 28
村莊英雄 village_hero 29
黑暗 darkness 30

其他實體函數 API

下面這些API提供了與遊戲中指定位置實體互動的API

在指定位置製造一次爆炸

mc.explode(pos,source,maxResistance,radius,isDestroy,isFire)
mc.explode(x,y,z,dimid,source,maxResistance,radius,isDestroy,isFire)

  • 參數:
    • pos : IntPos/ FloatPos
      引發爆炸的位置座標(或者使用x, y, z, dimid來確定實體位置)
    • source : Entity
      設置爆炸來源的實體對象,可以為Null
    • maxResistance : Float
      方塊最大爆炸抗性,低於此值的方塊會被破壞
    • radius : Float
      爆炸的範圍半徑,影響爆炸的波及範圍
    • isDestroy : Boolean
      爆炸是否破壞方塊
    • isFire : Boolean
      爆炸結束後是否留下燃燒的火焰
  • 返回值:是否成功製造爆炸
  • 返回值類型:Boolean

快速執行Molang表達式

en.quickEvalMolangScript(str)

  • 參數:
    • str : String
      Molang表達式
  • 返回值:表達式執行結果
  • 返回值類型:Float

關於Molang的詳細使用方法,請參考 MOLANG文檔 bedrock.dev