🎈 實體對象 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,...>

從現有實體獲取

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

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 則表示生成失敗

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

召喚新生物並獲取

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

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加載生物並獲取

通過此函數，使用指定的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，有以下這些屬性

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

• 實體當前朝向 屬性的詳細解釋見 基礎遊戲接口文檔
• 座標 和 腿部座標：如果這個實體為兩格高，則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

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

治療實體

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

設置實體自定義名稱

en.setCustomName(name)

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

獲取實體自定義名稱

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

其他實體函數 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