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 的監聽器會攔截事件:
遊戲不再處理它,就像它沒有發生過一樣,但其他插件的監聽器仍會被調用。見事件監聽。