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 的监听器会拦截事件:
游戏不再处理它,就像它没有发生过一样,但其他插件的监听器仍会被调用。见事件监听。