脚本引擎 - 插件开发概述

⛳ 放在前面

LegacyScriptEngine（以下简称LSE/脚本引擎）是一个基岩版官方服务端 Bedrock Dedicated Server（以下简称BDS）的插件框架，提供强大的跨语言脚本插件支持能力和稳定的开发API支持。

欢迎参与到脚本引擎的插件开发中来！

从这里开始，你将逐步熟悉脚本插件开发的基本要素和流程。

在接触开发之前，你需要对脚本引擎有一个成体系的认识。这里的文档，首先将帮助你建立一个大概的知识框架。
首先熟悉他们，这将是你学习开发的过程中非常重要的一环。

💊 数据类型

众所周知，类型系统通常都是一个设计框架中比较关键的部分。
因此，首先，你需要熟悉几种在使用 API 文档的过程中会频繁用到的数据类型。
这些数据类型的名词会频繁出现在开发文档当中，请务必首先对他们足够熟悉。

通用数据类型约定

虽然脚本语言通常是弱类型的，不需要关注具体的数据类型，但由于脚本引擎支持多种不同的脚本语言，为了方便对接API，下面定义一些通用的数据类型，以及到对应脚本语言类型的映射关系。

引擎数据类型	JavaScript 数据类型	Lua 数据类型	数据类型说明
Null	null/undefined	nil	空，未定义，不存在等等
Integer	Number	number	整数
Float	Number	number	浮点数（小数，实数）
String	String	string	字符串
Boolean	Boolean	boolean	布尔型
Function	Function	function	函数（方法）
Array	Array	table	数组（列表）
Object	Object	table	对象（映射，字典，表）
ByteBuffer	ArrayBuffer	table	字节数组

除了上述了标准类型之外，还存在一些引擎自定义的对象类型。

• IntPos - 整数 坐标对象（详见 基础游戏接口）
• FloatPos - 浮点数 坐标对象（详见 基础游戏接口）
• Player - 玩家对象（详见 玩家）- 在脚本引擎内实际注册的类名:LLSE_Player
• Entity - 实体对象（详见 实体）- 在脚本引擎内实际注册的类名:LLSE_Entity
• Block - 方块对象（详见 方块）- 在脚本引擎内实际注册的类名:LLSE_Block
• BlockEntity - 方块实体对象（详见 方块实体）- 在脚本引擎内实际注册的类名:LLSE_BlockEntity
• Item - 物品栏物品对象（详见 物品）- 在脚本引擎内实际注册的类名:LLSE_Item
• Device - 玩家设备信息对象（详见 玩家）- 在脚本引擎内实际注册的类名:LLSE_Device
• Container - 容器对象（详见 容器）- 在脚本引擎内实际注册的类名:LLSE_Container
• Objective - 计分项对象（详见 计分板）- 在脚本引擎内实际注册的类名:LLSE_Objective
• NBT - NBT Tag对象（详见 NBT）
• SimpleForm - 普通表单对象（详见 表单构建器）- 在脚本引擎内实际注册的类名:LLSE_SimpleForm
• CustomForm - 自定义表单对象（详见 表单构建器）- 在脚本引擎内实际注册的类名:LLSE_CustomForm
• Conf - 配置文件对象（详见 配置文件）
• DB - 数据库对象（详见 数据库）
• File - 文件对象（详见 文件读写）
• WSClient - WebSocket 客户端对象（详见 网络）
• Enum - 枚举类型，通常储存于某些类型中，提供一些限定范围的可选项

📌 API文档描述约定

众所周知，一个好的帮助文档自然离不开统一简洁的格式和一目了然的外观。
因此，为了文档的格式统一和规范，接下来，需要统一规定一下脚本引擎的帮助文档描述约定。

对于接下来你看到的所有API文档，都有这样的写作规则：

1. 关于文档中对 函数参数类型 的描述：
   函数参数将按照 参数名 : 参数类型 格式描述
   例如： cmd : String 表示一个字符串类型的变量cmd
   如果参数类型出现Array<...>表示一个以<>内的变量为内容的数组 / 列表

2. 关于文档中对 可选参数 的描述：
   如果在参数描述处出现 可选参数 则代表你可以不传入这个参数。
   当你不传入这个参数的时候，引擎将使用描述中给出的默认值。
   在API接口参数中，可选参数会被[ ]框起来。
   形如：pl.tell(msg[,type])，这里的type就属于可选参数

在熟悉上面这些基础设施之后，你可以开始逐步阅读其他各特定内容的文档了。
如果碰到遗忘了的东西，可以多翻回来看看。

📜 插件开发小贴士

这里，有一些在开发插件的时候的建议，希望可以帮到你

• 不要重复造轮子
  在条件允许的情况下，尽量使用他人已经编写好的特定功能的库，而不是每个功能都自己编写一遍。这样，有利于生态的整合和发展。
• 为用户思考
  在设计界面和配置的时候，最好考虑到用户的感受。UI和命令等对外交互的内容尽量做到清晰和一目了然，符合常规的使用习惯。
• 多角度思考创新
  鼓励大家向其他平台已有的优秀插件学习，也欢迎大家作出自己的创新。

📡 调试插件

你可以输入这些命令来进入相应的调试模式：

• jsdebug: JavaScript调试模式
• luadebug: Lua调试模式

在调试模式下，你输入的所有文本将被解析为脚本并实时执行，就像浏览器的开发工具的控制台那样。如果发生任何错误，你会看到一个错误报告。

你可以输入jsdebug/luadebug并回车以退出调试模式。