跳到正文
本頁目錄

🎨 基礎遊戲 API

下列這些API,提供了對遊戲內容進行 修改 和 擴展 的能力。

顯然,遊戲元素接口處於整個插件體系中的核心位置,關乎到對遊戲內容的控制和擴展能力。
腳本引擎提供了豐富強大的遊戲元素接口,為你發揮創意提供方便。

🔮 遊戲元素對象

對於遊戲元素的索引,腳本引擎使用專門類型的變量來跟蹤每一個遊戲元素,並稱其為「xx對象」,如「玩家對象」或者「方塊對象」。
你可以將其理解為遊戲元素的唯一標識符。

目前,腳本引擎擁有的遊戲元素對象如下:

對象類型名 對象稱呼 對象實際意義
IntPos 整數 座標對象 標識一個整數位置(如方塊座標)
FloatPos 浮點數 座標對象 標識一個浮點數位置(如實體座標)
DirectionAngle 方向角對象 標識一個歐拉角角度信息(如玩家朝向)
Player 玩家對象 標識一個玩家
Entity 實體對象 標識一個實體
Block 方塊對象 標識一個具體的方塊
Item 物品欄物品對象 標識一個物品欄中的物品
Container 容器對象 標識一個擁有格子、可以儲存和放置物品的容器
BlockEntity 方塊實體對象 標識一個方塊實體
Objective 記分項對象 標識一個記分板系統的記分項

在後續的文檔中,你會頻繁地接觸到他們。

🎯 座標對象

在遊戲中,數量眾多的 API 都需要提供座標。
引擎採用 IntPos 和 FloatPos 類型的對象來標示座標,稱之為「座標對象」。 座標對象的各個成員都是可讀寫的。

  1. IntPos對象 它的成員均為整數,多用來表示方塊座標等用整數表示的位置
    對於某個 IntPos 類型變量 pos,有如下這些成員:
成員 含義 類型
pos.x x 座標 Integer
pos.y y 座標 Integer
pos.z z 座標 Integer
pos.dim 維度文字名 String
pos.dimid 維度ID Integer

其中,維度ID 屬性的取值為:0 代表主世界,1 代表下界,2 代表末地 維度文字名 屬性的取值分別為:"主世界","下界","末地"

如果某種情況下維度無效,或者無法獲取,你會發現dimid的值為-1

  1. FloatPos對象 它的成員均為浮點數,多用來表示實體座標等用無法用整數表示的位置
    對於某個 FloatPos 類型變量 pos,有如下這些成員:
成員 含義 類型
pos.x x 座標 Float
pos.y y 座標 Float
pos.z z 座標 Float
pos.dim 維度文字名 String
pos.dimid 維度ID Integer

其中,維度ID 屬性的取值為:0 代表主世界,1 代表下界,2 代表末地 維度文字名 屬性的取值分別為:"主世界","下界","末地"

如果某種情況下維度無效,或者無法獲取,你會發現dimid的值為-1

座標對象輔助接口

對於自然支持面向對象的腳本語言,你可以直接構造座標對象,並傳入x, y, z, dimid參數
對於某些對面向對象支持一般的語言,腳本引擎也提供了輔助接口,幫助更方便地生成一個座標對象

生成一個整數座標對象

[JavaScript] new IntPos(x,y,z,dimid)
[Lua] IntPos(x,y,z,dimid)

  • 參數:
  • x : Integer
    x 座標
  • y : Integer
    y 座標
  • z : Integer
    z 座標
  • dimid : Integer
    維度ID:0 代表主世界,1 代表下界,2 代表末地
  • 返回值:一個整數座標對象
  • 返回值類型:IntPos

生成一個浮點數座標對象

[JavaScript] new FloatPos(x,y,z,dimid)
[Lua] FloatPos(x,y,z,dimid)

  • 參數:
  • x : Float
    x 座標
  • y : Float
    y 座標
  • z : Float
    z 座標
  • dimid : Integer
    維度ID:0 代表主世界,1 代表下界,2 代表末地
  • 返回值:一個浮點數座標對象
  • 返回值類型:FloatPos

📐 方向角對象

引擎採用 DirectionAngle 對象來標示一個歐拉角,稱之為「方向角對象」。
它的兩個成員均為浮點數,多用來表示實體的朝向等方向數據 方向角對象的各個成員都是可讀寫的。

對於某個 DirectionAngle 類型變量 ang,有如下這些成員:

成員 含義 類型
ang.pitch 俯仰角(-90° ~ 90°) Float
ang.yaw 偏航角(旋轉角) Float

由於MC的實體系統不存在 自轉 的概念,所以沒有翻滾角相關數據

創建偏航角

[JavaScript] new DirectionAngle(pitch, yaw)
[Lua] DirectionAngle(pitch, yaw)

  • 參數:
  • pitch : Float
    俯仰角
  • yaw : Float
    偏航角(旋轉角)
  • 返回值:一個方向角對象
  • 返回值類型:DirectionAngle

將偏航角轉換為基本朝向

ang.toFacing()

  • 返回值:當前方向角對象所指示的基本朝向
  • 返回值類型:Integer

返回值為0-3,代表 北東南西 四個基本朝向。用於快速確定實體面向的大致方向

獲取結構NBT

mc.getStructure(pos1, pos2, ignoreBlocks = false, ignoreEntities = false)

  • 參數:

  • pos1 : IntPos 對角座標1,填寫方式與 fill命令 的 from 參數類似

  • pos2 : IntPos 對角座標2,填寫方式與 fill命令 的 to 參數類似

  • ignoreBlocks : Boolean 忽略方塊

  • ignoreEntities : Boolean 忽略實體

  • 返回值類型:NbtCompound

放置結構NBT

mc.setStructure(nbt, pos, mirror = 0, rotation = 0)

  • 參數:

  • nbt : NbtCompound

  • pos : IntPos 放置座標

  • mirror : Integer 鏡像模式

    • 0: 不镜像 1: X轴 2: Z轴 3: XZ轴
  • rotation : Integer 旋轉角度

    • 0: 不旋转 1: 旋转90° 2: 旋转180° 3: 旋转270°
  • 返回值類型:Boolean