跳到正文
本頁目錄

API 的工作方式

LSE 的 API 在每種語言中都相同:參考只描述一次,由各引擎映射到自己的語言。本頁說明它的結構: 腳本在全局作用域中能找到什麼,它拿到的對象是什麼,以及引擎何時調用它提供的函數。

腳本一開始就有的東西

LSE 在運行入口腳本之前,把 API 綁定到每個插件的全局作用域中。你不需要 import 或 require 它。

全局函數:

  • log、colorLog 和 fastLog 向服務器控制台輸出;setTimeout、setInterval 和 clearInterval 稍後運行代碼 (見腳本輔助 API)。Node.js 引擎使用 Node.js 自己的 setTimeout 和 setInterval。

命名空間,即帶有靜態函數的對象:

名稱 內容 參考
mc 遊戲:事件(mc.listen)、命令、玩家、實體、方塊、物品、表單、計分板 GameAPI、EventAPI、GuiAPI
ll 加載器和插件:版本、插件信息、ll.exports / ll.imports、ll.onUnload ll
logger 插件的可配置日誌 日誌
data 數據輔助:玩家數據、JSON、MD5、SHA-1、Base64 其他數據
money 經濟系統 經濟系統
File 文件與目錄 文件、目錄與文件
network HTTP 請求(WebSocket 客戶端和 HTTP 服務器是對象 WSClient 和 HttpServer) 網絡
system 系統命令、進程和系統信息 系統調用、系統信息
NBT 解析 NBT,以及 NBT 標籤類型 NBT
i18n 插件文本的翻譯 國際化
Format Minecraft 文本的格式代碼 遊戲實用工具

枚舉,例如用於命令的 PermType 和 ParamType,也是全局的。

對象

API 的大部分功能通過對象完成。你有兩種方式得到對象:

  • 來自遊戲,即 API 返回或傳給你的函數的值:來自 mc.getPlayer 或 onJoin 監聽器的 Player,以及 Entity、 Block、Item、Container,命令回調中的 CommandOrigin。
  • 自己創建,用構造函數:new JsonConfigFile(path)、new KVDatabase(dir)、new DBSession(type, params)、 new WSClient()、new IntPos(x, y, z, dimid)、new NbtCompound(...)。在 Lua 中直接調用類,不寫 new: JsonConfigFile(path)。

參考中把這些類型稱為 Player、Entity、Block 等;在引擎中註冊的類名為 LLSE_Player、LLSE_Entity、 LLSE_Block……,參考概述的「數據類型」一節列出了它們。

玩家和實體是引用,不是副本

Player 或 Entity 對象指向遊戲中的玩家或實體:訪問屬性時才讀取,調用函數會作用於遊戲。它持有一個弱引用:玩家離開或實體消失後, 它的屬性返回 Null。所以不要長期保存 Player 對象。保存能標識玩家的信息(pl.xuid、pl.name),需要時再用 mc.getPlayer 獲取對象。

值與類型

參考使用通用的類型名(Integer、Float、String、Boolean、Array、Object、Null……),每個引擎把它們映射到 自己的類型:Object 在 JavaScript 中是對象,在 Lua 中是 table;Null 在 JavaScript 中是 null 或 undefined, 在 Lua 中是 nil。參考概述有完整的對照表和文檔的約定:參數寫作 名称 : 类型,可選參數用 [ ] 括起。

許多函數失敗時返回 Null(玩家不在線、表單無法發送):使用前先檢查。另一些函數,例如 SQL 數據庫的函數,則會拋出錯誤。

你的代碼何時運行

插件加載時,引擎運行一次入口腳本。插件做的其他一切,都發生在它交給 API 的函數中:

  • 事件監聽器(mc.listen),每次事件發生時調用;
  • 命令回調(mc.newCommand、mc.regPlayerCmd、mc.regConsoleCmd),有人運行命令時調用;
  • 表單回調(pl.sendForm、pl.sendModalForm),玩家回答或關閉表單時調用;
  • 定時任務(setTimeout、setInterval),時間到時調用;
  • 卸載函數(ll.onUnload),插件卸載時調用。

這些函數在服務器線程上運行,夾在遊戲自身的工作之間。耗時的函數會拖住服務器:讓監聽器保持簡短,不要在 onTick 這類頻繁的事件中做繁重的工作。

如果你的函數拋出錯誤,LSE 會捕獲它,並在控制台中記錄,同時給出事件或回調以及你的插件名;插件會繼續運行。調用 API 時參數太少或類型不對,會拋出一個指明該 API 和你的插件的錯誤。

事件會發給每個監聽器

事件發生時,LSE 按註冊順序(一般就是插件的加載順序)調用每個插件對它的監聽器。返回 false 的監聽器會攔截事件: 遊戲不再處理它,就像它沒有發生過一樣,但其他插件的監聽器仍會被調用。見事件監聽。

接下來