🏃‍♂️ 玩家對象 API

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

獲取一個玩家對象

從事件或API獲取

通過註冊事件監聽函數，獲取到BDS給出的與相關事件有關的玩家對象
詳見 事件監聽文檔 - EventAPI

從現有玩家獲取

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

mc.getPlayer(info)

• 參數：
  • info : String
    玩家的名字、XUID、UniqueId、RuntimeId或者UUID
• 返回值：生成的玩家對象
• 返回值類型：Player
  • 如返回值為 Null 則表示獲取玩家失敗

獲取所有在線玩家

此函數會返回一個玩家對象的數組，其中每個對象都對應了一個服務器中的玩家

mc.getOnlinePlayers()

• 返回值：在線的玩家對象列表
• 返回值類型：Array<Player,Player,...>

注意：不要長期保存一個玩家對象
當玩家退出服務器時，對應的玩家對象將同時釋放。因此，如果有長期操作某個玩家的需要，請通過上述途徑獲取實時的玩家對象

玩家對象 - 屬性

每一個玩家對象都包含一些固定的對象屬性。對於某個特定的玩家對象pl，有以下這些屬性

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

• 座標 和 腿部座標：玩家為兩格高，pos為玩家視角高度的座標，feetPos為遊戲內顯示的方塊座標
• 玩家遊戲模式 屬性的取值為：0 代表生存模式，1 代表創造模式，2 代表冒險模式，3 代表旁觀者模式
• 玩家真實名字 屬性儲存的字符串可以被認為是可靠的，他們不會被改名而變動
• 玩家設備IP地址 屬性儲存了玩家的設備IP以及端口號，格式類似12.34.567.89:1111
• 玩家當前朝向 屬性的詳細解釋見 基礎遊戲接口文檔
• 操作權限等級 屬性的對照表如下：

玩家對象 - 函數

每一個玩家對象都包含一些可以執行的成員函數（成員方法）。對於某個特定的玩家對象pl，可以通過以下這些函數對這個玩家進行一些操作

判斷玩家是否為OP

pl.isOP()

• 返回值：玩家是否為OP

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var open = pl.isOP();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    open = pl:isOP()

斷開玩家連接

pl.kick([msg])
pl.disconnect([msg])

• 參數：

  • msg : String
    （可選參數）被踢出玩家出顯示的斷開原因。
    如果不傳入，默認為“正在從服務器斷開連接”

• 返回值：是否成功斷開連接

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.kick();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:kick()

發送一個文本消息給玩家

pl.tell(msg[,type])
pl.sendText(msg[,type])

• 參數：

  • msg : String
    待發送的文本

  • type : Integer
    （可選參數）發送的文本消息類型，默認為0

• 返回值：是否成功發送

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    //对于一个玩家对象pl
    pl.tell("Welcome back ~ ", 5);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:tell("Welcome back ~ ", 5)

設置玩家顯示標題

pl.setTitle(content[,type[,fadeInTime,stayTime,fadeOutTime]])

• 參數：

  • content : String
    欲設置標題內容

  • type : Integer
    （可選參數）設置的標題類型，默認為2

  type參數	消息類型
  0	清空（Clear）
  1	重設（Reset）
  2	設置主標題（SetTitle）
  3	設置副標題（SetSubTitle）
  4	設置Actionbar（SetActionBar）
  5	設置顯示時間（SetDurations）
  6	Json型主標題（TitleTextObject）
  7	Json型副標題（SubtitleTextObject）
  8	Json型Actionbar（ActionbarTextObject）

  • fadeInTime : Integer
    （可選參數）淡入時間，單位為 Tick ，默認為10

  • stayTime: Integer

  （可選參數）停留時間，單位為 Tick ，默認為70

  • fadeOutTime:Integer

  （可選參數）淡出時間，單位為 Tick，默認為20

• 返回值：是否成功發送

• 返回值類型：Boolean

廣播一個文本消息給所有玩家

mc.broadcast(msg[,type])

• 參數：

  • msg : String
    待發送的文本

  • type : Integer
    （可選參數）發送的文本消息類型，默認為0

• 返回值：是否成功發送

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    mc.broadcast("Hello everyone ~ ");

  • Lua
    Lua

    -- 对于一个玩家对象pl
    mc.broadcast("Hello everyone ~ ")

在屏幕上方顯示消息(類似於成就完成)

pl.sendToast(title,message)

• 參數：

  • title : String
    待發送的標題

  • message : String
    待發送的文本

• 返回值：是否成功發送

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.sendToast("Hello", "everyone ~");

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:sendToast("Hello", "everyone ~")

以某個玩家身份執行一條命令

pl.runcmd(cmd)

• 參數：

  • cmd : String
    待執行的命令

• 返回值：是否執行成功

• 返回值類型： Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.runcmd("tp ~ ~50 ~");

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:runcmd("tp ~ ~50 ~")

以某個玩家身份說話

pl.talkAs(text)

• 參數：

  • text : String
    模擬說話內容

• 返回值：是否執行成功

• 返回值類型： Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.talkAs("Hello everyone ~ ");

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:talkAs("Hello everyone ~ ")

獲取玩家到座標的距離

pl.distanceTo(pos) pl.distanceToSqr(pos)

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

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

以某個玩家身份向某玩家說話

pl.talkTo(text,target)

• 參數：

  • text : String
    模擬說話內容
  • target : Player
    模擬說話對象

• 返回值：是否執行成功

• 返回值類型： Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.talkAs(anotherpl, "Hello ~ ");

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:talkAs(anotherpl, "Hello everyone ~ ")

傳送玩家至指定位置

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

• 參數：

  • pos: IntPos/ FloatPos 目標位置座標 （或者使用x, y, z, dimid來確定玩家位置）

  • rot: DirectionAngle

  （可選參數）傳送後玩家的朝向，若缺省則與傳送前朝向相同

• 返回值：是否成功傳送

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    //对于一个玩家对象pl
    pl.teleport(pos);

  • Lua
    Lua

    pl:teleport(pos)

殺死玩家

pl.kill()

• 返回值：是否成功執行

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.kill();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:kill()

對玩家造成傷害

pl.hurt(damage,type,source)

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

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

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.hurt(20);
    // 使用枚举
    pl.hurt(20, ActorDamageCause.EntityAttack);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:hurt(20)

治療玩家

pl.heal(health)

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

設置玩家的生命值

pl.setHealth(health)

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

為玩家設置傷害吸收屬性

pl.setAbsorption(value)

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

為玩家設置攻擊傷害屬性

pl.setAttackDamage(value)

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

為玩家設置最大攻擊傷害屬性

pl.setMaxAttackDamage(value)

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

為玩家設置跟隨範圍

pl.setFollowRange(value)

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

為玩家設置擊退抵抗屬性

pl.setKnockbackResistance(value)

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

為玩家設置幸運屬性

pl.setLuck(value)

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

為玩家設置移動速度屬性

pl.setMovementSpeed(value)

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

為玩家設置水下移動速度屬性

pl.setUnderwaterMovementSpeed(value)

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

為玩家設置岩漿上移動速度屬性

pl.setLavaMovementSpeed(value)

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

設置玩家最大生命值

pl.setMaxHealth(health)

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

設置玩家飢餓值

pl.setHungry(hunger)

• 參數:
  • hunger : Integer
    飢餓值數
• 返回值: 是否成功
• 返回值類型: Boolean

使指定玩家著火

pl.setFire(time,isEffect)

• 參數：

  • time : Integer
    著火時長，單位秒
  • isEffect : Boolean 會不會有火的效果

• 返回值：是否成功著火

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setFire(20,true);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setFire(20,true)

熄滅玩家

pl.stopFire()

• 返回值: 是否已被熄滅
• 返回值類型: Boolean

縮放玩家

pl.setScale(scale)

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

重命名玩家

pl.rename(newname)

• 參數：

  • newname : String
    玩家的新名字

• 返回值：是否重命名成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.rename("Steve");

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:rename("Steve")

獲取玩家當前站立所在的方塊

pl.getBlockStandingOn()

• 返回值：當前站立在的方塊對象

• 返回值類型：Block

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var bl = pl.getBlockStandingOn();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    bl = pl:getBlockStandingOn()

獲取玩家對應的設備信息對象

pl.getDevice()

• 返回值：玩家對應的設備信息對象
• 返回值類型：Device

設備信息對象儲存了與玩家設備有關的某些信息，如設備IP地址、設備類型、網絡延遲等信息。
關於設備信息對象的其他信息請參考 設備信息對象 API

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var dv = pl.getDevice();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    dv = pl:getDevice()

獲取玩家主手中的物品對象

pl.getHand()

• 返回值：玩家主手中的物品對象
• 返回值類型：Item

此處獲取的物品對象為引用。也就是說，修改此處返回的物品對象，或使用其API，就相當於直接操作玩家主手中對應的物品

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var it = pl.getHand();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    it = pl:getHand()

獲取玩家副手的物品對象

pl.getOffHand()

• 返回值：玩家副手中的物品對象
• 返回值類型：Item

此處獲取的物品對象為引用。也就是說，修改此處返回的物品對象，或使用其API，就相當於直接操作玩家副手中對應的物品

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var it = pl.getOffHand();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    it = pl:getOffHand()

獲取玩家物品欄的容器對象

pl.getInventory()

• 返回值：玩家物品欄對應的容器對象
• 返回值類型：Container

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

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var ct = pl.getInventory();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    ct = pl:getInventory()

獲取玩家盔甲欄的容器對象

pl.getArmor()

• 返回值：玩家盔甲欄對應的容器對象
• 返回值類型：Container

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

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var ct = pl.getArmor();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    ct = pl:getArmor()

獲取玩家末影箱的容器對象

pl.getEnderChest()

• 返回值：玩家末影箱對應的容器對象
• 返回值類型：Container

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

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var ct = pl.getEnderChest();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    ct = pl:getEnderChest()

獲取玩家的重生座標

pl.getRespawnPosition()

• 返回值：重生點座標

• 返回值類型：IntPos

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var pos = pl.getRespawnPosition();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pos = pl:getRespawnPosition()

修改玩家的重生座標

pl.setRespawnPosition(pos)
pl.setRespawnPosition(x,y,z,dimid)

• 參數：

  • pos : IntPos或FloatPos
    重生座標（或者使用x, y, z, dimid來確定重生位置）

• 返回值：是否成功修改

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    pl.setRespawnPosition(pos);

  • Lua
    Lua

    pl.setRespawnPosition(pos)

給予玩家一個物品

pl.giveItem(item[, amount])

• 參數：

  • item : Item
    給予的物品對象

  • amount: Integer

  （可選參數）給予物品對象的數量，若提供此參數則物品對象自身的Count屬性將被忽略 - 返回值：是否成功給予 - 返回值類型：Boolean

如果玩家物品欄已滿，將拋出多餘物品

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.giveItem(item);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:giveItem(item)

清除玩家背包中所有指定類型的物品

pl.clearItem(type[, count])

• 參數：
  • type : String
    要清除的物品對象類型名
  • count : Integer
    （可選參數）要清除的物品數量
• 返回值：清除的物品個數
• 返回值類型：Integer

將玩家物品欄、主手、副手、盔甲欄中所有物品的type屬性與此字符串進行比較
如果相等，則清除此物品

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.clearItem("minecraft:dirt");
    pl.clearItem("minecraft:dirt", 114514);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:clearItem("minecraft:dirt")
    pl:clearItem("minecraft:dirt", 1919)

刷新玩家物品欄、盔甲欄

pl.refreshItems()

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

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

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.refreshItems();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:refreshItems()

刷新玩家加載的所有區塊

pl.refreshChunks()

• 返回值：是否成功刷新

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.refreshChunks();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:refreshChunks()

修改玩家操作權限

pl.setPermLevel(level)

• 參數：

  • level : Integer
    目標操作權限等級

• 返回值：是否成功修改

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setPermLevel(0);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setPermLevel(0)

修改玩家遊戲模式

pl.setGameMode(mode)

• 參數：

  • mode : Integer
    目標遊戲模式，0為生存模式，1為創造模式，2為冒險模式, 6為觀察者模式

• 返回值：是否成功修改

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setGameMode(0);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setGameMode(0)

提高玩家經驗等級

pl.addLevel(count)

• 參數：

  • count : Integer
    要提高的經驗等級

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.addLevel(1);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:addLevel(1)

降低玩家經驗等級

pl.reduceLevel(count)

• 參數：

  • count : Integer
    要降低的經驗等級

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.reduceLevel(1);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:reduceLevel(1)

獲取玩家經驗等級

pl.getLevel()

• 返回值：玩家的經驗等級

• 返回值類型：Integer

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var lv = pl.getLevel();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    lv = pl:getLevel()

設置玩家經驗等級

pl.setLevel(count)

• 參數：

  • count : Integer
    要設置的經驗等級

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setLevel(1);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setLevel(1)

重置玩家經驗

pl.resetLevel()

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.resetLevel();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:resetLevel()

獲取玩家當前經驗值

pl.getCurrentExperience()

• 返回值：玩家當前經驗值

• 返回值類型：Integer

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.getCurrentExperience();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:getCurrentExperience()

設置玩家當前經驗值

pl.setCurrentExperience(count)

• 參數：

  • count : Integer
    要設置的經驗值

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setCurrentExperience(1);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setCurrentExperience(1)

獲取玩家總經驗值

pl.getTotalExperience()

• 返回值：玩家總經驗值

• 返回值類型：Integer

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var xp = pl.getTotalExperience();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    xp = pl:getTotalExperience()

設置玩家總經驗值

pl.setTotalExperience(count)

• 參數：

  • count : Integer
    要設置的經驗值

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setTotalExperience(1);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setTotalExperience(1)

提高玩家經驗值

pl.addExperience(count)

• 參數：

  • count : Integer 要提高的經驗值

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.addExperience(1);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:addExperience(1)

降低玩家經驗值

pl.reduceExperience(count)

• 參數：

  • count : Integer 要降低的經驗值

• 返回值：是否設置成功

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.reduceExperience(1);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:reduceExperience(1)

獲取玩家升級所需的經驗值

pl.getXpNeededForNextLevel()

• 返回值：玩家升級所需的經驗值
• 返回值類型：Integer

注意，此方法在計算時會忽略當前經驗值

• 示例：
  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    var ndxp = pl.getXpNeededForNextLevel();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    ndxp = pl:getXpNeededForNextLevel()

傳送玩家至指定服務器

pl.transServer(server,port)

• 參數：

  • server : String
    目標服務器IP / 域名

  • port : Integer
    目標服務器端口

• 返回值：是否成功傳送

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

      // 对于一个玩家对象pl
      pl.transServer("123.45.67.89", 23333);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:transServer("123.45.67.89", 23333)

使玩家客戶端崩潰

pl.crash()

• 返回值：是否成功執行

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.crash();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:crash()

設置玩家自定義側邊欄

pl.setSidebar(title,data[,sortOrder])

• 參數：

  • title : String
    側邊欄標題
  • data : Object<String-Integer>
    側邊欄對象內容對象
    對象中的每個鍵 - 值對將被設置為側邊欄內容的一行
  • sortOrder : Number
    （可選參數）側邊欄內容的排序順序。0為按分數升序，1為按分數降序。默認值為1

• 返回值：是否成功設置

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setSidebar("title", {
        aaaa: 3,
        bbb: 12,
        cc: 7,
    });

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setSidebar("title", {
        "aaaa" = 3,
        "bbb" = 12,
        "cc" = 7
    })

移除玩家自定義側邊欄

pl.removeSidebar()

• 返回值：是否成功移除

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.removeSidebar();

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:removeSidebar()

設置玩家看到的自定義Boss血條

pl.setBossBar(uid,title,percent,colour)

• 參數：

  • uid : Number
    唯一標識符，不可衝突重複！一個uid對於一行bar
  • title : String
    自定義血條標題
  • percent : Integer
    血條中的血量百分比，有效範圍為0~100。0為空血條，100為滿
  • colour : Integer
    血條顏色(默認值為2(RED))

• 返回值：是否成功設置

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.setBossBar(1145141919, "Hello ~ ", 80, 0);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:setBossBar(1145141919, "Hello ~ ", 80, 0)

移除玩家的自定義的指定Boss血條

pl.removeBossBar(uid)

• 參數：

  • uid : Number
    標識符，與setBossBar對應！

• 返回值：是否成功移除

• 返回值類型：Boolean

• 示例：

  • JavaScript
    JavaScript

    // 对于一个玩家对象pl
    pl.removeBossBar(1145141919);

  • Lua
    Lua

    -- 对于一个玩家对象pl
    pl:removeBossBar(1145141919)

獲取在線玩家對應的NBT對象

pl.getNbt()

• 返回值：玩家的NBT對象
• 返回值類型：NbtCompound

寫入在線玩家對應的NBT對象

pl.setNbt(nbt)

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

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

獲取玩家對應的NBT對象

mc.getPlayerNbt(uuid)

• 參數：
  • uuid : String
    玩家的UUID
• 返回值：玩家的NBT對象
• 返回值類型：NbtCompound
  • 如果玩家不存在或沒有存檔數據，則返回值為 Null

寫入玩家對應的NBT對象

mc.setPlayerNbt(uuid,nbt[,forceCreate,isOnlineMode])

• 參數：
  • uuid : String
    玩家的UUID
  • nbt : NbtCompound
    NBT對象
  • forceCreate : Boolean 可選參數
    當該 UUID 沒有對應存檔記錄時，是否創建離線玩家數據。默認值為 false
  • isOnlineMode : Boolean 可選參數
    僅在 forceCreate 為 true 時生效。決定新建玩家數據是否使用在線模式。默認值為 true
• 返回值：是否成功寫入
• 返回值類型：Boolean

覆蓋玩家對應的NBT對象的特定NbtTag

mc.setPlayerNbtTags(uuid,nbt,tags)

• 參數：
  • uuid : String
    玩家的UUID
  • nbt : NbtCompound
    NBT對象
  • tags : Array<String> 需要覆蓋的NbtTag
• 返回值：是否成功覆蓋對應的Tag
• 返回值類型：Boolean

從存檔中刪除玩家對應的NBT對象的全部內容

mc.deletePlayerNbt(uuid)

• 參數：
  • uuid : String
    玩家的UUID
• 返回值：是否刪除成功
• 返回值類型：Boolean

獲取全部已保存玩家 UUID

mc.getAllPlayerUuids([isOnlineMode])

• 參數：
  • isOnlineMode : Boolean 可選參數
    為 true 時返回登錄了微軟賬號玩家的 UUID；為 false 時返回離線模式玩家的 UUID，默認為 false
• 返回值：已保存玩家 UUID 字符串列表
• 返回值類型：Array<String,String,...>

為玩家增加一個Tag

pl.addTag(tag)

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

為玩家移除一個Tag

pl.removeTag(tag)

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

檢查玩家是否擁有某個Tag

pl.hasTag(tag)

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

獲取玩家擁有的所有Tag列表

pl.getAllTags()

• 返回值：玩家所有的 tag 字符串列表
• 返回值類型：Array<String,String,...>

獲取玩家的Abilities能力列表（來自玩家NBT）

pl.getAbilities()

• 返回值：玩家所有能力信息的鍵 - 值對列表對象
• 返回值類型：Object<String-任意类型>

鍵 - 值對列表中的每一項形如："mayfly": 1 等等

獲取玩家的Attributes屬性列表（來自玩家NBT）

pl.getAttributes()

• 返回值：玩家所有屬性對象的數組
• 返回值類型：Array<Object,Object,...>

數組中的每一項為一個鍵 - 值對列表對象Object，Attributes對象默認含有Base Current DefaultMax DefaultMin Max Min Name 等幾種內容 。其內容形如：

{
  Base: 0,
  Current: 0,
  DefaultMax: 1024,
  DefaultMin: -1024,
  Max: 1024,
  Min: -1024,
  Name: "minecraft:luck"
}

獲取玩家疾跑狀態

pl.isSprinting()

• 返回值：玩家疾跑狀態
• 返回值類型：Boolean

設置玩家疾跑狀態

pl.setSprinting(sprinting)

• 參數：
  • sprinting : Boolean
    是否為疾跑狀態
• 返回值：是否設置成功
• 返回值類型：Boolean

獲取視線方向實體

pl.getEntityFromViewVector([maxDistance])

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

獲取視線方向方塊

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

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

向玩家發送數據包

pl.sendPacket(packet)

• 參數：
  • packet : Packet
    數據包
• 返回值：是否成功，如果pl不存在，返回Null
• 返回值類型：Boolean

獲取玩家所在群系ID

pl.getBiomeId()

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

獲取玩家所在群系名稱

pl.getBiomeName()

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

設置玩家Ability屬性

pl.setAbility(AbilityID,value)

• 參數：
  • AbilityID : Integer
    Ability的ID
  • value : Boolean
    是否開啟
• 返回值：無作用
• 返回值類型：Boolean

獲取玩家全部藥水效果

pl.getAllEffects()

• 返回值：玩家所有的藥水效果id（見下表）
• 返回值類型：Array<Integer,Integer,...>

為玩家添加一個藥水效果

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

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

為玩家移除一個藥水效果

pl.removeEffect(id)

• 參數：
  • id : Number 藥水效果的id（見下表）
• 返回值：操作是否成功
• 返回值類型：Boolean

將玩家對象轉換實體對象

en.toEntity()

• 返回值：轉換成的實體對象
• 返回值類型：Entity
  • 如果轉換失敗，則返回 Null

判斷是否為模擬玩家

pl.isSimulatedPlayer()

• 返回值：是否為模擬玩家
• 返回值類型：Boolean

模擬玩家（由於與玩家API重合過多，未生成新的模擬玩家類）

創建一個模擬玩家

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

• 參數：
  • name : String
    模擬玩家名稱
  • pos : IntPos/ FloatPos
    生成生物的位置的座標對象（或者使用x, y, z, dimid來確定生成位置）
• 返回值：生成的（模擬）玩家對象
• 返回值類型：Player
  • 如返回值為 Null 則表示生成失敗

模擬玩家 - 函數

每一個模擬玩家對象都包含一些可以執行的成員函數（成員方法）。對於某個特定的模擬玩家對象sp，可以通過以下這些函數對這個模擬玩家進行一些操作

模擬重生

sp.simulateRespawn()

• 返回值：是否成功模擬操作
• 返回值類型：'Boolean'

參考：mojang-gametest docs

模擬攻擊

sp.simulateAttack([target])

• 參數：

  • target : Entity
    （可選參數）攻擊目標，默認為視線方向上的實體

• 返回值：是否成功模擬操作

• 返回值類型：Boolean

參考：mojang-gametest docs

模擬破壞

sp.simulateDestroy([pos,face]) sp.simulateDestroy([block,face])

• 參數：

  • pos :IntPos
    （可選參數）要破壞的方塊的座標，默認為視線方向上的方塊
  • block :Block
    （可選參數）要破壞的方塊，默認為視線方向上的方塊
  • face :Integer
    （可選參數）從哪面破壞，

• 返回值：是否成功模擬操作

• 返回值類型：Boolean

參考：mojang-gametest docs

模擬斷開連接

sp.simulateDisconnect()

• 返回值：是否成功模擬操作
• 返回值類型：Boolean

模擬交互

sp.simulateInteract([target]) sp.simulateInteract([pos,face]) sp.simulateInteract([block,face])

• 參數：

  • target : Entity
    （可選參數）模擬交互目標，默認為視線方向上的方塊或實體
  • pos :IntPos
    （可選參數）模擬交互目標，默認為視線方向上的方塊或實體
  • block :Block
    （可選參數）模擬交互目標，默認為視線方向上的方塊或實體
  • face :Number
    （可選參數）模擬交互目標方塊的面

• 返回值：是否成功模擬操作

• 返回值類型：Boolean

參考：mojang-gametest docs

模擬跳躍

sp.simulateJump()

• 返回值：是否成功模擬操作
• 返回值類型：Boolean

參考：mojang-gametest docs

模擬看向某方塊或實體

sp.simulateLookAt(pos, [lookDuration]) sp.simulateLookAt(entity, [lookDuration]) sp.simulateLookAt(block, [lookDurration])

• 參數：

  • target : Entity
    要看向的實體
  • pos :IntPos / FloatPos
    要看向的座標
  • block :Block
    要看向的方塊
  • lookDuration: Integer
    模擬玩家看向目標的持續時間
    0 = 立刻, 1 = 持續, 2 = 不變直到移動

• 返回值：是否成功模擬操作

• 返回值類型：Boolean

參考：mojang-gametest docs

模擬設置身體角度

sp.simulateSetBodyRotation(rot)

• 參數：

  • rot : Number
    要設置的角度

• 返回值：是否成功模擬操作

• 返回值類型：Boolean

參考：mojang-gametest docs

相對玩家座標系移動

sp.simulateLocalMove()

• 參數：

  • pos : IntPos / FloatPos
    移動方向
  • speed : Number
    （可選參數）移動速度，默認為1

• 返回值：是否請求移動成功

• 返回值類型：Boolean

相對世界座標系移動

sp.simulateWorldMove()

• 參數：

  • pos : IntPos / FloatPos
    移動方向
  • speed : Number
    （可選參數）移動速度，默認為1

• 返回值：是否請求移動成功

• 返回值類型：Boolean

直線移動到座標

sp.simulateMoveTo()

• 參數：

  • pos : IntPos / FloatPos
    目標位置
  • speed : Number
    （可選參數）移動速度，默認為1

• 返回值：是否請求移動成功

• 返回值類型：Boolean

參考：mojang-gametest docs
注：如需自動尋路，請考慮使用 模拟导航移动

模擬導航移動

sp.simulateNavigateTo(entity[,speed) sp.simulateNavigateTo(pos[,speed])

• 參數：

  • entity : Entity
    導航目標
  • pos : IntPos / FloatPos
    導航目標
  • speed : Number
    （可選參數）移動速度，默認為1

• 返回值：是否能到達指定位置以及導航路徑，結構：{isFullPath:Boolean,path:Number[3][]}

• 返回值類型：Object

參考：mojang-gametest docs
返回值示例：

{
  isFullPath: false,
  path: [
    [
      -8,
      0,
      -3
    ],
    [
      -7,
      0,
      -2
    ],
    [
      -6,
      0,
      -2
    ],
    [
      -5,
      0,
      -2
    ],
    [
      -4,
      0,
      -1
    ],
    [
      -3,
      0,
      -1
    ],
    [
      -2,
      0,
      -1
    ],
    [
      -1,
      0,
      0
    ]
  ]
}

此數據的目標座標為(0,2,0)，路徑終點為(-1,0,0)，所以isFullPath為false，但由於路徑不為空，所以模擬玩家將會移動至(-1,0,0)座標

模擬導航移動（多目標）

sp.simulateNavigateTo(posArray[,speed])

• 參數：

  • posArray : IntPos[] / FloatPos[]
    導航目標
  • speed : Number
    （可選參數）移動速度，默認為1

• 返回值：是否成功模擬操作

• 返回值類型：Boolean

參考：mojang-gametest docs

模擬使用物品

sp.simulateUseItem([slot,pos,face,relative]) sp.simulateUseItem([item,pos,face,relative])

• 參數：

  • item : Item
    （可選參數）要使用的物品，默認為選中物品
  • slot : Number
    （可選參數）要使用的物品所在的槽，默認為選中物品
  • pos : IntPos
    （可選參數）目標座標，默認為朝向方塊座標
  • face : Number
    （可選參數）目標方塊的面，默認為0
  • relative : FloatPos
    （可選參數）相對方塊偏移座標，默認為{0.5,0.5,0.5}

• 返回值：是否成功模擬操作

• 返回值類型：Boolean

參考：mojang-gametest docs

模擬停止破壞方塊

sp.simulateStopDestroyingBlock()

• 返回值：是否成功模擬操作
• 返回值類型：Boolean

參考：mojang-gametest docs

模擬停止交互

sp.simulateStopInteracting()

• 返回值：是否成功模擬操作
• 返回值類型：Boolean

參考：mojang-gametest docs

模擬停止移動

sp.simulateStopMoving()

• 返回值：是否成功模擬操作
• 返回值類型：Boolean

參考：mojang-gametest docs

模擬停止使用物品

sp.simulateStopUsingItem()

• 返回值：是否成功模擬操作
• 返回值類型：Boolean

參考：mojang-gametest docs