diff --git a/CHANGELOG.md b/CHANGELOG.md
index cfb4240e..e791ca01 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.3] - 2026-02-13
+
+### Added
+- Added AI Agents support 
+
 ## [0.17.2] - 2026-02-04
 
 ### Fixed
diff --git a/docs/llms.txt b/docs/llms.txt
new file mode 100644
index 00000000..e63ed9be
--- /dev/null
+++ b/docs/llms.txt
@@ -0,0 +1 @@
+脚本引擎 配置与数据处理接口文档 这里为你提供了处理 大量数据 时的多种可选方案在插件工作过程中难免会碰到需要处理配置和大量游戏相关数据的场景。 脚本引擎为脚本插件提供了大量基础设施包括配置文件、数据库、经济系统等。 方便开发者专注于业务代码实现而非纠结于这些方面的技术细节。 配置文件 API配置文件一般用于将插件的某些可供用户修改的设置项独立成文件以方便修改某些设置。 因此配置文件的内容和格式一般需要有一定的可读性。 脚本引擎提供 ConfigFile 配置文件接口来完成这个任务。 当然你也可以手动读写文件来协助相关配置文件的操作。 说明配置文件类型的选择配置文件格式的选择将影响你可以储存的配置数据类型。 请按需做出选择。 JSON 格式配置文件创建 打开一个 JSON 配置文件JavaScript new JsonConfigFilepathdefault Lua JsonConfigFilepathdefault配置文件所在路径以BDS根目录为基准 如果配置文件路径中有目录尚不存在脚本引擎会自动创建可选参数配置文件的默认内容。 如果初始化时目标文件不存在引擎将新建一个配置文件并将此处的默认内容写入文件中。 如果不传入此参数新建时的配置文件将为空我们建议你在 BDS根目录plugins插件名字 目录下建立名为configjson的配置文件以保持各插件的配置统一对于一个 JSON 配置文件对象conf你有这些读写接口可用初始化配置项方便函数confinitnamedefault配置项名字配置项初始化时写入的值这里提供了一种简便的方法来初始化配置文件避免了需要手写默认配置文件内容的麻烦 如果init访问的配置项不存在那么引擎将在配置文件中自动创建此项并写入给出的默认值 如果init访问的配置项已经存在引擎将读取并返回配置文件中已有的值写入配置项confsetnamedata配置项名字要写入的配置数据。允许的数据类型有 Integer Float String Boolean Array Object 其中Array 和 Object 内部仅能嵌套上面这些元素读取配置项confgetnamedefault配置项名字可选参数当读取失败时返回的默认值 默认为Null删除配置项confdeletename配置项名字如果这个配置项你不需要了为了避免在他人修改配置文件时引起迷惑你可以选择将它删除 Ini 格式配置文件创建 打开一个 Ini 配置文件JavaScript new IniConfigFilepathdefault Lua IniConfigFilepathdefault配置文件所在路径以BDS根目录为基准 如果配置文件路径中有目录尚不存在脚本引擎会自动创建可选参数配置文件的默认内容。 如果初始化时目标文件不存在引擎将新建一个配置文件并将此处的默认内容写入文件中。 如果不传入此参数新建时的配置文件将为空我们建议你在 BDS根目录plugins插件名字 目录下建立名为configini的配置文件以保持各插件的配置统一对于一个 Ini 配置文件对象conf你有这些读写接口可用初始化配置项方便函数confinitsectionnamedefault配置项键名配置项名字配置项初始化时写入的值。允许的数据类型有 Integer Float String Boolean这里提供了一种简便的方法来初始化配置文件避免了需要手写默认配置文件内容的麻烦 如果init访问的配置项不存在那么引擎将在配置文件中自动创建此项并写入给出的默认值 如果init访问的配置项已经存在引擎将读取并返回配置文件中已有的值写入配置项confsetsectionnamedata配置项键名配置项名字要写入的配置数据。允许的数据类型有 Integer Float String Boolean如果配置项不存在接口会自动创建读取配置项读取字符串 confgetStrsectionnamedefault 读取整数项 confgetIntsectionnamedefault 读取浮点数 confgetFloatsectionnamedefault 读取布尔值 confgetBoolsectionnamedefault 配置项键名配置项名字可选参数当读取失败时返回的默认值 默认为0删除配置项confdeletesectionname配置项键名配置项名字如果这个配置项你不需要了为了避免在他人修改配置文件时引起迷惑你可以选择将它删除 其他的通用接口函数对于一个配置文件对象conf你可以使用这些辅助用途的通用接口重新加载文件中的配置项confreload为了性能考虑配置文件接口对读操作进行缓存每次读取操作都从直接内存中读取而写入才会直接写入磁盘文件。考虑到配置文件可能被用户修改当你确认用户已经修改配置文件之后需要使用此函数刷新配置文件的内存缓存数据。关闭配置文件confclose配置文件关闭之后请勿继续使用获取配置文件路径confgetPath读取整个配置文件的内容confread写入整个配置文件的内容confwritecontent写入的内容 数据库 API数据库一般用于插件可持久化地储存某些插件所生成和处理的数据。 不同于配置文件数据库一般没有可读性方面的要求而对性能和稳定性有相当的考虑。 脚本引擎提供统一数据库接口来完成这个任务。 具体实现上引擎提供了两种不同的数据库格式键 值对格式的NoSQL数据库和表格形式的SQL数据库。你可以按需使用。 目录 KVDB 键值对数据库键值对nosql数据库 SQL数据库sql数据库附 各SQL的官方文档 SQLitehttpswwwsqliteorgdocshtml MySQLhttpsdevmysqlcomdoc 键 值对 NoSQL数据库键 值对数据库适用于储存键 值形式的数据 形如nameapple value5等等。 底层使用 LevelDBhttpsgithubcomgoogleleveldb 实现创建 打开一个键值对数据库在使用数据库之前你先需要给出一个数据库路径接口将打开创建指定的数据库并返回一个数据库对象。 一个LevelDB数据库是由多个文件组成的所以你需要传入一个文件夹的路径数据库文件会被储存于这个文件夹当中。 如果这个目录已含有一个数据库将打开它否则会新建一个。JavaScript new KVDatabasedir Lua KVDatabasedir数据库的储存目录路径以BDS根目录为基准当给出的目录不存在时将尝试自动逐层创建对应的目录路径成功打开数据库后你可以使用下面的接口来进行相关的操作。 对于一个数据库对象db有以下这些函数写入数据项dbsetnamedata数据项名字要写入的数据。允许使用的数据类型有 Integer Float String Boolean Array Object 其中Array 和 Object 内部仅能嵌套上面出现的这些元素读取数据项dbgetname数据项名字删除数据项dbdeletename数据项名字获取所有数据项名字dblistKey关闭数据库dbclose数据库关闭之后请勿继续使用 SQL数据库SQL数据库适用于使用SQL语句处理大量的关系型数据。接口底层使用跨数据库操作框架实现可对接绝大多数市面常用SQL数据库。注以下API若未注明均可能会抛出异常建议使用各语言的异常处理语句嵌套。JavaScript可使用try catch语句Lua可使用pcall。一般情况下未抛出错误即代表调用成功。 如果您是JavaScript插件开发者您还可以尝试使用YoyohttpsgiteecomYoyo封装的LLDB链式操作库主要面向不了解SQL语法的新手开发者。详情 点击这里httpsgiteecomYoyoyoyomcbelitexloaderitemblobmastersqlyoyoSqlitejs20200md打开一个SQL数据库会话由于需要做到多数据库兼容 连接数据库需要传入一个包含连接参数的对象或字符串。JavaScript new DBSessiontype params Lua DBSessiontype params数据库的类型支持sqlite3和mysql连接参数连接参数JavaScript new DBSessionstr Lua DBSessionstr形如filemydbdbkv mysqlrootpasswordlocalhost3306db的连接字符串连接参数 键 用途 可用数据库 示例 默认值 path 指定数据库所在路径 SQLite pluginstestdb create 数据库不存在是否自动创建 SQLite truefalse true readonly 以只读模式打开 SQLite truefalse false readwrite 以读写模式打开 SQLite truefalse true 执行SQL并获取结果集sessionquerysql 要查询的SQL语句返回数组的第1行result0为结果集的表头列名剩余行为结果数据若查询结果为 a b ll 233 h 114 则用query方法返回值表示为jsona bll 233h 114执行SQL但不获取结果sessionexecsql sessionexecutesql要执行的SQL语句获取当前会话是否为打开状态sessionisOpen关闭数据库会话sessioncloseSQL预准备语句 预准备语句Prepared Statement是SQL的一个重要部分。它的实现原理是先将含有未知参数的SQL语句发往服务端处理、编译再绑定参数最终执行并返回结果。各个SQL的预准备语句实现可能不同其预准备语句的表示方法也可能存在差异所以请务必仔细阅读文档直接去阅读对应SQL的官方文档则更好。 预准备语句的主要作用是防止SQL注入攻击一种很常见的、危险的攻击。如果在未经检验的情况下直接使用用户输入的数据就像BDS一样 xD就可能会造成免密码登录甚至数据丢失注入执行DROP TABLE或DROP DATABASE等严重后果。所以在处理用户输入的数据时更推荐使用预准备语句。其次它可以在服务器只编译一次语句的情况下实现多次输入。准备一个预准备语句sessionpreparesql 要准备的SQL语句各个SQL的预准备语句SQLitesqlSELECT FROM table WHERE id INSERT INTO table VALUES X YINSERT INTO table VALUES X Y Z V 注 httpswwwsqliteorgc3refbindblobhtml MySQLsqlSELECT FROM table WHERE id INSERT INTO table VALUES X YINSERT INTO table VALUES X Y Z预准备语句对象 属性 属性 含义 类型 另见 stmtaffectedRows 获取该预准备语句执行后影响的行数仅对INSERT UPDATE DELETE REPLACE 等语句生效 Integer SQLitehttpswwwsqliteorgc3refchangeshtml MySQLhttpsdevmysqlcomdoccapi80enmysqlaffectedrowshtml stmtinsertId 获取该INSERTUPDATEREPLACE语句执行后最后一个更改行的行号关于行号的解释详见官方文档 Integer SQLitehttpswwwsqliteorgc3reflastinsertrowidhtml MySQLhttpsdevmysqlcomdoccapi80enmysqlstmtinsertidhtml 这些对象属性都是只读的无法被修改并且只能在语句执行之后获取到绑定参数到一个SQL语句stmtbindval要绑定的值 stmtbindobj要绑定的对象等同于遍历此对象并执行bindval keystmtbindarr要绑定的数组等同于遍历此数组并执行bindvalstmtbindval index要绑定的值要绑定到的参数索引从0开始stmtbindval name要绑定的值要绑定到的参数的参数名在绑定完成后应调用stmtexecute执行语句否则语句将不会被执行一个样例搞懂几个重载函数jslet stmt sessionprepareINSERT INTO table VALUSE a b c d e f g hlet values c have youd finishede yourf homeworkstmtbindvalues cdef将会被绑定stmtbindLLSE 将会绑定到astmtbind mojang 将会绑定到b和gstmtbind114514 7 将会绑定到h执行当前语句stmtexecute步进到下一行结果stmtstep stmtnext获取当前结果行stmtfetch获取所有结果行stmtfetchAllstmtfetchAllcallback回调函数用于遍历结果行在回调函数中返回false可终止遍历重置当前语句状态至待执行stmtreset重新执行预准备语句stmtreexec清除所有已绑定的参数stmtclear样例jslet dat let modified let session nullfunction initdb if fileexistspluginsMyPlugin filemkdirpluginsMyPluginsession new DBSessionsqlite path pluginsMyPlugindatdbsessionexecCREATE TABLE IF NOT EXISTS test player CHAR100 NOT NULLcoins INTEGER NOT NULL 这里创建数据表后SQLite会自动添加一个隐藏的ROWID行insertId就是这个隐藏的ROWID行的值 另如果数据库自带INTEGER类型主键则ROWID即为该主键 使用dowhile语句function loadData let stmt sessionprepareSELECT FROM testdo 准备并执行后默认在第一行let row stmtfetchdatrowplayer rowcoins while stmtstep 第一次执行时步进到第二行并成功获取到结果返回true最后一行时再步进则返回false 使用回调函数function loadData2 sessionprepareSELECT FROM testexecutefetchAllplayer coins datplayer coinsfunction writeData let keys Objectkeysmodifiedlet stmt sessionprepareUPDATE FROM test WHERE player SET coins executefor let i 0 i keyslength i let v modifiedkeysistmtbindkeysi v 绑定数组参数 绑定完成后自动执行语句stmtclear 清除已经绑定的值mcregPlayerCmdgetcoin Get a coin pl argsdatplrealNamemodifiedplrealName 经济系统 API在很多服务器中经济系统是非常关键的一环。 为了解决传统使用计分板经济系统的种种问题脚本引擎提供了对接LLMoney经济系统的接口可以与其他各系列插件数据互通。 LLMoney除了拥有传统经济系统的能力之外还有查询金额变动历史、操作离线玩家经济等额外能力。 LeviLamina在安装时附带了LLMoney插件因此无需额外安装就可以直接使用此接口。 设置玩家的存款金额PlayersetMoneyvaluemoneysetxuidvalue要操作的玩家的XUID标识符要设置的金额 获取玩家的存款金额PlayergetMoneymoneygetxuid要读取的玩家的XUID标识符增加玩家的存款PlayeraddMoneyvaluemoneyaddxuidvalue要操作的玩家的XUID标识符要增加的金额 减少玩家的存款PlayerreduceMoneyvaluemoneyreducexuidvalue要操作的玩家的XUID标识符要减小的金额 进行一笔转账PlayertransMoneytargetmoneynotemoneytransxuid1xuid2moneynote付款的玩家的XUID标识符收款的玩家的XUID标识符如果你使用 PlayertransMoneytarget可以是玩家对象要支付的金额 可选参数给这笔转账附加一些文字说明查询历史账单PlayergetHistorytimemoneygetHistoryxuidtime要操作的玩家的XUID标识符查询从现在开始往前time秒的记录其中结果为一系列记录对象组成的数组。对于每个记录对象record有如下的键和对应的值 键 值的意义 数据类型 recordfrom 此项交易的发起者玩家XUID String recordto 此项交易的接收者玩家XUID String recordmoney 此项交易的金额 Integer recordtime 此项交易发生时的时间字符串 String recordnote 此交易的附加说明信息 String 时间字符串的格式为YYYYmmdd hhmmss删除账单历史记录moneyclearHistorytime删除从现在开始往前time秒的记录 其他数据处理 API提供一些其他的常用数据处理接口。你可以自行使用并拓展。注意data是一个空类函数都是静态函数。变量转换为JSON字符串datatoJsonvarspace要转换为JSON字符串的变量。允许进行转换的数据类型有 Integer Float String Boolean Array Object 其中Array 和 Object 内部仅能嵌套上面出现的这些元素可选参数如果要格式化输出的字符串则传入此参数 代表每个缩进的空格数量这样输出的JSON串更适合人阅读 此参数默认为0即不对输出字符串进行格式化JSON字符串解析为变量dataparseJsonjson要转换为变量的JSON字符串MD5计算datatoMD5str要计算MD5的字符串 字节数组SHA1计算datatoSHA1str要计算SHA1的字符串 字节数组数据转Base64datatoBase64str要转化为Base64的字符串 字节数组Base64解码为数据datafromBase64base64 isBinary要解码的base64字符串返回数据类型是否为二进制数据默认为 false 玩家绑定数据在实际开发中经常有需要将某些数据和服务器中的某个玩家相关联并在插件的工作周期中不断维护这些数据的需求。 为此脚本引擎设计了玩家绑定数据接口。绑定数据接口使用键 值对的形式储存数据。 在你将数据绑定到某个玩家上以后即使在玩家对象超出作用域被销毁甚至当此玩家退出游戏时玩家绑定数据将仍然存在。当你再次获得这个玩家的玩家对象的时候仍然可以读取到之前储存的绑定数据。 只有当服务端关闭的时候所有的数据才会被统一销毁。由此脚本引擎给予开发者在插件的整个生命周期中跟踪某个特定玩家相关数据的能力。 对于某个特定的玩家对象pl有如下这些接口储存玩家绑定数据plsetExtraDatanamedata要储存到绑定数据的名字你要储存的绑定数据可以是Null获取玩家绑定数据plgetExtraDataname要读取的绑定数据的名字删除玩家绑定数据pldelExtraDataname要删除的绑定数据的名字 XUID 数据库XUID数据库让你可以即使在玩家离线的时候也可以查询玩家名字与XUID的对应关系。 当一个玩家第一次进服的时候他的名字和XUID就会被自动记录在内置 XUID 数据库中。使用下面的函数来进行相关查询根据玩家名查询XUIDdataname2xuidname要查询的玩家名根据XUID查询玩家名dataxuid2namexuid要查询的玩家XUID根据玩家名查询UUIDdataname2uuidname要查询的玩家名根据XUID查询玩家UUIDdataxuid2uuidxuid要查询的玩家XUID获取所有的玩家信息datagetAllPlayerInfo提示XUID数据库中储存的玩家名为玩家对象对应的realName字段 warning以下API均为0813新API使用以下API将导致插件无法兼容旧版根据XUID查询玩家信息datafromXuidxuid要查询玩家的XUID根据UUID查询玩家信息datafromUuiduuid要查询玩家的UUID根据名字查询玩家信息datafromNamename要查询玩家的名字 方块相关事件onBlockInteracted 方块接受玩家互动functionplayerblock与方块互动的玩家对象被互动的方块对象只有可以被互动的方块才会触发此事件如木桶、信标、制图台、磨石等 拦截事件对箱子、潜影盒、工作台无效onBlockChanged 方块改变functionbeforeBlockafterBlock改变前的方块对象改变后的方块对象detailssummary拦截此事件需要注意以下问题summary1部分事件导致的方块变化无法拦截 比如玩家挖掘放置 2对于方块与方块之间关系导致的变化部分不可拦截比如爆炸摧毁周围方块 实际上客户端看起来那边还是存在方块的但是已经是假方块了 3但是对于火把这种需要附着在其他方块上的方块如果因为附着方块被摧毁那么火把不会随之被破坏 4具体某些特性可以自行测试detailsonBlockExplode 发生由方块引起的爆炸functionsourceposradiusmaxResistanceisDestroyisFire爆炸来源的方块对象爆炸发生的坐标爆炸波及的半径爆炸可破坏的方块爆炸抗性上限爆炸是否破坏方块爆炸是否产生火焰onRespawnAnchorExplode 发生由重生锚引起的爆炸functionposplayer爆炸发生的重生锚的坐标试图使用重生锚的玩家onBlockExploded 方块被爆炸破坏functionblocksource被爆炸破坏的方块对象爆炸来源的实体对象onFireSpread 火焰蔓延functionpos火焰蔓延到的方块坐标onCmdBlockExecute 命令方块执行命令functioncmdposisMinecart执行的命令执行命令的命令方块坐标命令是否由命令方块矿车执行onContainerChange 容器内容改变functionplayercontainerslotNumoldItemnewItem操作容器的玩家对象被操作的容器的方块对象操作容器的格子位置第slotNum个格子格子中的原来旧物品对象格子中新的物品对象此处的 容器 为宽泛容器的概念包括箱子、桶等多种可以储存物品的容器都可以触发此事件对回调参数的解释 旧物品对象与新物品对象有多种不同的组合情况表示格子内不同的变化情况onProjectileHitBlock 方块被弹射物击中functionblocksource被击中的方块对象发射的弹射物实体如箭onRedStoneUpdate 发生红石更新functionblocklevelisActive发生红石更新的方块对象更新的红石能量等级015表示红石更新是激活还是熄灭 目前可以监测红石更新的方块种类有红石线、红石火把、红石中继器、红石比较器onHopperSearchItem 漏斗漏斗矿车检测可否吸取物品functionposisMinecartitem漏斗漏斗矿车所在的位置是否为漏斗矿车检测到的物品对象注在放置漏斗之后会在服务端反复不断触发这个事件 当你拦截事件之后漏斗就会无法吸取这个物品onHopperPushOut 漏斗输出物品functionposisMinecartitem漏斗漏斗矿车所在的位置是否为漏斗矿车准备输出的物品对象onPistonTryPush 活塞尝试推动functionpistonPosblock正在工作的活塞坐标尝试被推动的方块对象若活塞被方块阻挡无法推动此事件将会不停地循环触发onPistonPush 活塞推动functionpistonPosblock正在工作的活塞坐标被推动的方块对象注此事件与上事件不同上一个Try事件在活塞推动前尝试时触发此事件在推动完毕后触发onFarmLandDecay 耕地退化functionposentity退化的耕地的坐标造成耕地退化的实体onUseFrameBlock 操作物品展示框functionplayerblock操作物品展示框的玩家对象被操作的物品展示框方块对象注操作包括放置物品、取下物品、旋转物品。onLiquidFlow 液体方块流动functionfromto水源方块对象即将流经的方块位置 经济系统事件此处为脚本引擎内置经济系统相关的经济变动事件beforeMoneyAdd 玩家金额增加前事件functionxuidmoney金额变动的玩家的XUID增加的金额onMoneyAdd 玩家金额增加事件functionxuidmoney金额变动的玩家的XUID增加的金额beforeMoneyReduce 玩家金额减少前事件functionxuidmoney金额变动的玩家的XUID减少的金额onMoneyReduce 玩家金额减少事件functionxuidmoney金额变动的玩家的XUID减少的金额beforeMoneyTrans 玩家转账前事件functionfromtomoney发起转账的玩家的XUID接受转账的玩家的XUID转账的金额onMoneyTrans 玩家转账事件functionfromtomoney发起转账的玩家的XUID接受转账的玩家的XUID转账的金额beforeMoneySet 设置玩家金额前事件functionxuidmoney金额变动的玩家的XUID被设置的金额onMoneySet 直接设置玩家金额事件functionxuidmoney金额变动的玩家的XUID被设置的金额 实体相关事件onMobDie 生物死亡functionmobsourcecause死亡的实体对象伤害来源的实体对象可能为Null死亡原因注意当玩家死亡时除了触发onPlayerDie事件这个事件同样也会被触发一次onMobHurt 生物受伤包括玩家functionmobsourcedamagecause受伤的实体对象伤害来源的实体对象可能为Null受到的伤害数值受伤原因ActorDamageCause 为伤害原因枚举枚举值如下有问号的待验证待补充 ActorDamageCause 枚举 值 解释 ActorDamageCauseNone 1 其他 ActorDamageCauseOverride 0 非正常方式如脚本直接设置血量为0这种方式的伤害不会被盔甲与buff吸收 ActorDamageCauseContact 1 接触伤害如仙人掌 ActorDamageCauseEntityAttack 2 实体攻击 ActorDamageCauseProjectile 3 抛射物攻击 ActorDamageCauseSuffocation 4 窒息密封空间 ActorDamageCauseFall 5 掉落 ActorDamageCauseFire 6 燃烧 ActorDamageCauseFireTick 7 点燃 ActorDamageCauseLava 8 熔岩 ActorDamageCauseDrowning 9 溺水 ActorDamageCauseBlockExplosion 10 方块爆炸 ActorDamageCauseEntityExplosion 11 实体爆炸 ActorDamageCauseVoid 12 虚空 ActorDamageCauseSelfDestruct 13 自杀 ActorDamageCauseMagic 14 尖牙对生物造成的伤害、守卫者对生物造成的魔法伤害和药水伤害等 ActorDamageCauseWither 15 凋零效果 ActorDamageCauseStarve 16 饥饿 ActorDamageCauseAnvil 17 下落的铁砧 ActorDamageCauseThorns 18 荆棘 ActorDamageCauseFallingBlock 19 下落的方块 ActorDamageCausePiston 20 活塞 ActorDamageCauseFlyIntoWall 21 动能滑翔撞墙 ActorDamageCauseMagma 22 岩浆块 ActorDamageCauseFireworks 23 烟花 ActorDamageCauseLightning 24 闪电 ActorDamageCauseCharging 25 充能 ActorDamageCauseTemperature 26 温度 雪人 ActorDamageCauseFreezing 27 冰冻 ActorDamageCauseStalactite 28 被钟乳石砸到 ActorDamageCauseStalagmite 29 掉落到石笋上 ActorDamageCauseRamAttack 30 山羊冲撞 ActorDamageCauseSonicBoom 31 坚守着音爆攻击 ActorDamageCauseCampfire 32 营火 ActorDamageCauseSoulCampfire 33 灵魂营火 ActorDamageCauseMaceSmash 34 下落攻击 ActorDamageCauseAll 35 所有 onEntityExplode 发生由实体引起的爆炸functionsourceposradiusmaxResistanceisDestroyisFire爆炸来源的实体对象爆炸发生的坐标爆炸波及的半径爆炸可破坏的方块爆炸抗性上限爆炸是否破坏方块爆炸是否产生火焰onMobTrySpawn 发生于实体尝试自然生成functiontypeNamepos生成实体名称生成的坐标onMobSpawned 发生于实体自然生成完成functionentitypos生成的实体对象生成的坐标此事件为实体成功生成后触发不可直接拦截如需拦截请使用entitydespawn或entityremoveonProjectileHitEntity 实体被弹射物击中functionentitysource被击中的实体对象发射的弹射物实体如箭onWitherBossDestroy 凋灵破坏方块functionwitherBossAAbbaaBB凋灵的实体对象凋灵将破坏的区域长方体对角点A坐标凋灵将破坏的区域长方体对角点B坐标注意此事件不包括凋灵爆炸的破坏。onRide 生物骑乘functionentity1entity2尝试骑乘的实体对象被骑乘的实体对象注骑乘包括坐矿车、坐船、骑马、骑猪等。onStepOnPressurePlate 生物踩压力板functionentitypressurePlate踩压力板的实体对象被踩的压力板方块对象注生物踩压力板时将会反复多次触发此事件。onSpawnProjectile 弹射物创建functionshootertype发射弹射物的的实体对象弹射物标准类型名注已知可拦截的弹射物有鸡蛋、末影珍珠、雪球、三叉戟、箭、钓竿鱼钩。onProjectileCreated 弹射物创建完毕functionshooterentity创建此弹射物的的实体对象被创建的弹射物实体对象onNpcCmd NPC执行命令 warning此事件仅在096及更高版本中可用。functionnpcplcmd执行命令的NPC实体对象触发NPC命令执行的玩家对象NPC执行的命令如果有多条命令以分隔onChangeArmorStand 操作盔甲架functionasplslot被操作的盔甲架实体对象操作盔甲架的玩家对象装备栏编号onEntityTransformation 实体转变functionuniqueIdentity转变前的实体的唯一标识符转换完成的实体注此事件为 Addons 中实体的 TransformationComponent 激活时触发多用于引擎与Addon交互。由于转变前的实体指针很快被销毁因此只提供UniqueId。onEndermanTakeBlock 末影人搬运方块 warning此事件仅在0113及更高版本中可用。functionentity block pos搬运方块的末影人被搬运的方块被搬运的方块坐标 事件系统让插件可以 响应 特定的游戏事件让你可以在特定事件发生时执行代码下面这些API提供了监听游戏事件并做出响应的相关能力。 监听 API注册指定的监听函数。 当游戏中的某种事件发生时你设置的对应的监听函数将被引擎调用这时候你可以对相关事件进行处理。 注册监听器 mclisteneventcallback要监听的事件名见下方监听事件列表注册的监听函数函数相关参数见下 当指定的事件发生时BDS会调用你给出的监听函数并传入相应的参数拦截事件在脚本引擎的事件监听系统中一般你可以通过返回false来拦截某个可以被拦截的事件。拦截事件意味着在脚本拦截之后BDS将不再处理这个事件就像他从没发生过一样。 举例拦截某条聊天事件会造成所有人都看不到这条聊天消息不过拦截事件仅对BDS有效。 也就是说拦截事件并不影响其他有对应监听的脚本引擎脚本处理这个事件只是BDS无法再接收到它。避开误区有些时候在某些事件监听内部调用特定的API会造成死循环崩服请务必避免这些情况的发生 举例在onConsoleCmd事件监听中调用mcruncmdEx系列函数执行后台指令将导致死循环 监听事件列表侧边栏中给出了脚本引擎支持监听的各种事件的列表。提示你可以根据监听得到的游戏对象来获取他们的相关信息比如说方块的坐标、实体的名字等等。 同时这些对象的成员函数也都可以被调用。 注意传入的回调参数中有些有时候可能为 Null这需要在编写代码的时候做好判断检查 其他事件onScoreChanged 玩家计分板数值改变functionplayernumnamedisName计分板数值改变的玩家改变后的计分板数值计分板计分项名称计分板计分项的显示名称onTick 每个游戏刻触发functiononServerStarted 服务器启动完毕functiononConsoleCmd 服务端执行后台命令functioncmd执行的后台命令 玩家相关事件onPreJoin 玩家开始连接服务器functionplayer正在连接服务器的玩家对象注在这个监听函数中只能获取一些玩家的基础信息比如名字、IP、XUID等。因为此时玩家尚未完全进服onJoin 玩家进入游戏加载世界完成functionplayer进入游戏的玩家对象onLeft 玩家离开游戏functionplayer离开游戏的玩家对象onRespawn 玩家重生functionplayer重生的玩家对象onPlayerDie 玩家死亡functionplayersource死亡的玩家对象伤害来源的实体对象可能为NullonPlayerCmd 玩家执行命令functionplayercmd执行命令的玩家对象执行的命令onChat 玩家发送聊天信息functionplayermsg发送聊天信息的玩家对象发送的聊天消息onChangeDim 玩家切换维度functionplayerdimid切换维度的玩家对象前往维度的维度ID0为主世界1为下界2为末地提醒当玩家从末地通过返回传送门返回主世界时不会触发此事件。onJump 玩家跳跃functionplayer跳跃的玩家对象onSneak 玩家切换潜行状态functionplayerisSneaking切换潜行状态的玩家对象True表示玩家进入潜行状态False表示玩家退出潜行状态onAttackEntity 玩家攻击实体functionplayerentity攻击实体的玩家对象被攻击的实体对象onAttackBlock 玩家攻击方块functionplayerblockitem攻击方块的玩家对象被攻击的方块对象手持的物品对象onUseItem 玩家使用物品 functionplayeritem使用物品的玩家对象被使用的物品对象onUseItemOn 玩家对方块使用物品点击右键functionplayeritemblocksidepos使用物品的玩家对象被使用的物品对象被点击到的方块对象方块被点击的面 依次为0下 1上 2北 3南 4西 5东被点击的浮点位置注Win10客户端玩家右键会在服务端连续多次激发这个事件onUseBucketPlace 玩家使用桶倒出东西functionplayeritemblocksidepos使用物品的玩家对象被使用的物品对象被点击到的方块对象方块被点击的面 依次为0下 1上 2北 3南 4西 5东被点击的浮点位置注无论是手机还是Win10玩家可能会连续多次激发这个事件onUseBucketTake 玩家使用桶装进东西functionplayeritemtargetsidepos使用物品的玩家对象被使用的物品对象被点击到的方块对象或者实体对象方块被点击的面 依次为0下 1上 2北 3南 4西 5东被点击的浮点位置注无论是手机还是Win10玩家可能会连续多次激发这个事件onTakeItem 玩家捡起物品functionplayerentityitem捡起物品的玩家对象即将被捡起的物品的掉落物实体即将被捡起的物品对象onDropItem 玩家丢出物品functionplayeritem丢出物品的玩家对象被丢出的物品对象onEat 玩家正在吃食物functionplayeritem正在吃的玩家对象被吃的物品对象此处的 食物 为宽泛物品的概念包括常规食物、药水、牛奶、药品等多种可以被摄取的物品onAte 玩家吃下食物functionplayeritem正在吃的玩家对象被吃的物品对象onConsumeTotem 玩家消耗图腾functionplayer消耗图腾的玩家对象onEffectAdded 玩家获得效果functionplayereffectNameamplifierduration获得效果的玩家对象获得的效果名称 minecrafteffect效果获得的效果倍率 效果等级 1获得的效果时长 单位tickonEffectRemoved 玩家移除效果functionplayereffectName被移除效果的玩家对象被移除的效果名称 minecrafteffect效果onEffectUpdated 玩家刷新效果functionplayereffectNameamplifierduration刷新效果的玩家对象获得的效果名称 minecrafteffect效果获得的效果倍率 效果等级 1获得的效果时长 单位tickonStartDestroyBlock 玩家开始破坏方块 点击左键functionplayerblock正在破坏方块的玩家对象正在被破坏的方块对象onDestroyBlock 玩家破坏方块完成functionplayerblock破坏方块的玩家对象被破坏的方块对象onPlaceBlock 玩家尝试放置方块functionplayerblockface放置方块的玩家对象将要放置的方块对象被放置的方块的朝向。 存在问题 当玩家尝试放置方块时该事件将持续被触发。afterPlaceBlock 玩家放置方块functionplayerblock放置方块的玩家对象被放置的方块对象onOpenContainer 玩家打开容器方块functionplayerblock打开容器方块的玩家对象被打开的容器方块对象此处的 容器 为宽泛容器的概念包括箱子、桶等多种可以储存物品的容器都可以触发此事件onCloseContainer 玩家关闭容器方块functionplayerblock关闭容器方块的玩家对象被关闭的容器方块对象由于监听函数下限制目前支持监听关闭的容器有箱子minecraftchest、木桶minecraftbarrelonInventoryChange 玩家物品栏变化functionplayerslotNumoldItemnewItem操作物品栏的玩家对象操作物品栏的格子位置第slotNum个格子格子中的原来旧物品对象格子中新的物品对象对回调参数的解释 旧物品对象与新物品对象有多种不同的组合情况表示格子内不同的变化情况onChangeSprinting 玩家改变疾跑状态functionplayersprinting要改变疾跑状态的玩家对象要改变成的疾跑状态注可在下一游戏刻执行playersetSprintingfalse达到拦截效果onSetArmor 玩家改变盔甲栏functionplayerslotNumitem改变盔甲栏的玩家对象盔甲栏序号范围03盔甲栏中的物品对象onUseRespawnAnchor 玩家使用重生锚functionplayerpos使用重生锚的玩家对象被使用的重生锚的位置onOpenContainerScreen 玩家打开容器类GUIfunctionplayer尝试打开GUI的玩家对象注此事件非常强力甚至可以拦截打开背包。onExperienceAdd 玩家获得经验functionplayerexp获得经验的玩家对象获得的经验值onPlayerPullFishingHook 玩家使用钓鱼竿钓起实体functionplayerentityitem使用钓鱼竿的玩家对象钓起的实体鱼钩拉起任意实体都会触发该事件不一定是物品实体钓起的物品对象如果钓到的不是物品则返回nullonBedEnter 玩家上床functionplayerpos上床的玩家对象床的位置onPlayerInteractEntity 玩家交互实体 warning此事件仅在095及以后版本可用functionplayer entity pos交互实体的玩家对象被交互的实体对象交互坐标 脚本引擎 游戏元素接口文档 下列这些API提供了对游戏内容进行 修改 和 扩展 的能力。 显然游戏元素接口处于整个插件体系中的核心位置关乎到对游戏内容的控制和扩展能力。 脚本引擎提供了丰富强大的游戏元素接口为你发挥创意提供方便。 游戏元素对象对于游戏元素的索引脚本引擎使用专门类型的变量来跟踪每一个游戏元素并称其为「xx对象」如「玩家对象」或者「方块对象」。 你可以将其理解为游戏元素的唯一标识符。目前脚本引擎拥有的游戏元素对象如下 对象类型名 对象称呼 对象实际意义 IntPos 整数 坐标对象 标识一个整数位置如方块坐标 FloatPos 浮点数 坐标对象 标识一个浮点数位置如实体坐标 DirectionAngle 方向角对象 标识一个欧拉角角度信息如玩家朝向 Player 玩家对象 标识一个玩家 Entity 实体对象 标识一个实体 Block 方块对象 标识一个具体的方块 Item 物品栏物品对象 标识一个物品栏中的物品 Container 容器对象 标识一个拥有格子、可以储存和放置物品的容器 BlockEntity 方块实体对象 标识一个方块实体 Objective 记分项对象 标识一个记分板系统的记分项 在后续的文档中你会频繁地接触到他们。 坐标对象在游戏中数量众多的 API 都需要提供坐标。 引擎采用 IntPos 和 FloatPos 类型的对象来标示坐标称之为「坐标对象」。坐标对象的各个成员都是可读写的。1 IntPos对象它的成员均为整数多用来表示方块坐标等用整数表示的位置 对于某个 IntPos 类型变量 pos有如下这些成员 成员 含义 类型 posx x 坐标 Integer posy y 坐标 Integer posz z 坐标 Integer posdim 维度文字名 String posdimid 维度ID Integer 其中维度ID 属性的取值为0 代表主世界1 代表下界2 代表末地如果某种情况下维度无效或者无法获取你会发现dimid的值为12 FloatPos对象它的成员均为浮点数多用来表示实体坐标等用无法用整数表示的位置 对于某个 FloatPos 类型变量 pos有如下这些成员 成员 含义 类型 posx x 坐标 Float posy y 坐标 Float posz z 坐标 Float posdim 维度文字名 String posdimid 维度ID Integer 其中维度ID 属性的取值为0 代表主世界1 代表下界2 代表末地如果某种情况下维度无效或者无法获取你会发现dimid的值为1坐标对象辅助接口对于自然支持面向对象的脚本语言你可以直接构造坐标对象并传入x y z dimid参数 对于某些对面向对象支持一般的语言脚本引擎也提供了辅助接口帮助更方便地生成一个坐标对象生成一个整数坐标对象JavaScript new IntPosxyzdimid Lua IntPosxyzdimidx 坐标y 坐标z 坐标维度ID0 代表主世界1 代表下界2 代表末地 生成一个浮点数坐标对象JavaScript new FloatPosxyzdimid Lua FloatPosxyzdimidx 坐标y 坐标z 坐标维度ID0 代表主世界1 代表下界2 代表末地 方向角对象引擎采用 DirectionAngle 对象来标示一个欧拉角称之为「方向角对象」。 它的两个成员均为浮点数多用来表示实体的朝向等方向数据方向角对象的各个成员都是可读写的。对于某个 DirectionAngle 类型变量 ang有如下这些成员 成员 含义 类型 angpitch 俯仰角90 90 Float angyaw 偏航角旋转角 Float 由于MC的实体系统不存在 自转 的概念所以没有翻滚角相关数据创建偏航角JavaScript new DirectionAnglepitch yaw Lua DirectionAnglepitch yaw俯仰角偏航角旋转角将偏航角转换为基本朝向angtoFacing返回值为03代表 北东南西 四个基本朝向。用于快速确定实体面向的大致方向获取结构NBTmcgetStructurepos1 pos2 ignoreBlocks false ignoreEntities false放置结构NBTmcsetStructurenbt pos mirror 0 rotation 0 方块对象 API在脚本引擎中使用「方块对象」来操作和获取某一类方块的相关信息。获取一个方块对象从事件或API获取通过注册事件监听函数或者调用某些返回方块对象的函数获取到BDS给出的与相关事件有关的方块对象 详见 事件监听文档 EventAPIEventAPIListenzhmd 通过方块坐标获取通过此函数来手动生成对象注意你要获取的方块必须处于已被加载的范围中否则会出现问题mcgetBlockpos mcgetBlockxyzdimid方块所在坐标或者使用x y z dimid来确定方块位置 注意不要长期保存一个方块对象 当方块对象对应的方块被销毁时对应的方块对象将同时释放。因此如果有长期操作某个方块的需要请通过上述途径获取实时的方块对象方块对象 属性每一个方块对象都包含一些固定的对象属性。对于某个特定的方块对象bl有以下这些属性 属性 含义 类型 blname 游戏内显示的方块名称 String bltype 方块标准类型名 String blid 方块的游戏内id Integer blpos 方块所在坐标 IntPos bltileData 方块数据值 Integer blvariant The block variant Integer bltranslucency 方块透明度 Integer blthickness 方块厚度 Integer blisAir 方块是否为空气 Boolean blisBounceBlock 是否为可弹跳方块 Boolean blisButtonBlock 是否为按钮方块 Boolean blisCropBlock 是否为农作物方块 Boolean blisDoorBlock 是否为门方块 Boolean blisFenceBlock 是否为栅栏方块 Boolean blisFenceGateBlock 是否为栅栏门方块 Boolean blisThinFenceBlock 是否为细栅栏方块 Boolean blisHeavyBlock 是否为重的方块 Boolean blisStemBlock 是否为干方块 Boolean blisSlabBlock 是否为半转方块 Boolean blisUnbreakable 方块是否为不可破坏 Boolean blisWaterBlockingBlock 方块是否可阻挡水 Boolean 这些对象属性都是只读的无法被修改方块对象 函数每一个方块对象都包含一些可以执行的成员函数成员方法。对于某个特定的方块对象bl可以通过以下这些函数对这个方块进行一些操作破坏方块bldestroydrop是否生成掉落物获取方块对应的NBT对象blgetNbt写入方块对应的NBT对象blsetNbtnbtNBT对象关于NBT对象的更多使用请参考 NBT接口文档NbtAPINBTzhmd注意慎重使用此api请考虑使用 mcsetBlock 代替获取方块的BlockStateblgetBlockState方便函数协助解析方块BlockState并转换为Object方便读取与解析 等价于脚本执行blockgetNbtgetTagstatestoObject判断方块是否拥有容器blhasContainer如箱子、桶等容器他们各自拥有一个属于自己的容器对象获取方块所拥有的容器对象blgetContainer关于容器对象的更多使用请参考 容器对象 API文档Containerzhmd判断方块是否拥有方块实体blhasBlockEntity获取方块所拥有的方块实体blgetBlockEntity删除方块所拥有的方块实体blremoveBlockEntity关于方块实体对象的更多使用请参考 方块实体对象 API文档GameAPIBlockEntityzhmd其他方块函数 API下面这些API提供了与游戏中指定位置方块互动的API设置指定位置的方块mcsetBlockpos blockObject mcsetBlockpos blockString tileData mcsetBlockx y z dimId blockObject mcsetBlockx y z dimId blockString tileData目标方块位置或者使用 x、y、z、dimId 来确定方块位置要设置成的方块对象或方块 NBT 数据方块标准类型名如minecraftstone方块状态值同原版 setBlock 指令的 tileData默认为0仅通过方块类型名放置方块时有效通过此函数将一个坐标对应的方块设置成另一个类似于命令 setblock在指定位置生成粒子效果mcspawnParticlepostype mcspawnParticlexyzdimidtype目标生成位置或者使用x y z dimid来确定方块位置要生成的粒子效果名称可查阅wiki得知粒子效果名称可以查阅Minecraft Wikihttpszhminecraftwikiw粒子类型得知在传入参数的时候不要忘记命名空间前缀。类似于 minecraftheartparticle 方块实体对象 API在脚本引擎中使用「方块实体对象」来操作和获取与特定方块关联的附加数据。 注意方块实体对象 不是一种 实体他们之间并没有特别的关系获取一个方块实体对象通过方块获取对于已存在的方块对象bl有blgetBlockEntity 注意不要长期保存一个方块实体对象 当方块对象对应的方块被销毁时对应的方块实体对象将同时释放。因此如果有长期操作某个方块实体的需要请通过上述途径获取实时的方块实体对象方块实体对象 属性每一个方块实体对象都包含一些固定的对象属性。对于某个特定的方块实体对象be有以下这些属性 属性 含义 类型 bename The block entity name example containerchest String bepos 方块实体对应方块所在的坐标 IntPos betype 方块实体对象的类型ID Integer 这些对象属性都是只读的无法被修改方块实体对象 函数每一个方块实体对象都包含一些可以执行的成员函数成员方法。对于某个特定的方块实体对象be可以通过以下这些函数对这个方块实体进行一些操作获取方块实体对应的NBT对象begetNbt写入方块实体对应的NBT对象besetNbtnbtNBT对象关于NBT对象的更多使用请参考 NBT接口文档NbtAPINBTzhmd获取方块实体对应的方块对象begetBlock 命令相关 API下面这些API提供了在游戏中注册、监听自定义命令的接口执行一条后台命令mcruncmdcmd待执行的命令JavaScriptjsmcruncmdsay HelloLualuamcruncmdsay Hello执行一条后台命令强化版mcruncmdExcmd待执行的命令 成员 含义 类型 ressuccess 是否执行成功 Boolean resoutput BDS执行命令后的输出结果 String noteruncmdEx 与普通 runcmd 实现区别非常大在于 Ex 版本拥有隐藏输出的机制执行结果不会输出至控制台因此如果有需要要手动用log 函数将结果输出JavaScriptjsvar result mcruncmdExsay Hellologresultoutput命令注册 API这里提供了注册自定义命令的接口。通过对接 BDS 内置的命令系统你注册的命令可以由玩家、控制台、命令方块、NPC等各种游戏中可以执行命令的对象所使用在addon 中也可以使用这里所注册的命令。 warning命令中除了可变参数String RawText Message等外均不能包含非英文小写字母注册一条顶层命令mcnewCommandcmddescriptionpermissionflagalias待注册的命令命令描述文本可选参数指令执行所需权限可选参数默认值 0x80 目前直接按此输入即可后续会进行相关修改可选参数命令的别名 可以为命令设置多个别名执行的时候相当于触发同一条命令 执行权限 含义 PermTypeAny 任何人都可以执行这条指令 PermTypeGameMasters 只有OP可以执行这条指令默认值 PermTypeConsole 只有控制台可以执行这条指令 tip顶层命令也就是类似 list gamerule 这种在 之后第一个输入的部分注册完顶层命令后此函数会返回一个指令对象。接下来对于这个命令的功能扩展都需要在这个指令对象中进行指令对象 函数通过指令对象你可以为这个命令注册各式各样的形式、功能。假设有一个叫 Command的指令对象则有下面这些成员函数设置指令别名CommandsetAliasalias指令别名新增一个指令枚举选项CommandsetEnumnamevalues枚举名用于设置参数时区分枚举枚举的有效值新增一个必选参数CommandmandatorynametypeenumNameidentifierenumOptions参数名用于执行指令时识别参数命令参数类型枚举名仅 ParamType 为 Enum 时有效用于区分枚举选项参数标识特殊情况下用于唯一识别参数一般可用 enumName 或 name 代替参数选项设置为 1 可在指令提示中展开枚举选项 如 action TagChangeAction 会变成 addremove新增一个可选参数CommandoptionalnametypeenumNameidentifierenumOptions参数名用于执行指令时识别参数命令参数类型枚举名仅 ParamType 为 Enum 时有效用于区分枚举选项参数标识特殊情况下用于唯一识别参数一般可用 enumName 或 name 代替参数选项设置为 1 可在指令提示中展开枚举选项 如 action TagChangeAction 会变成 addremove有效的命令参数类型及解释 命令参数类型 含义 ParamTypeBool 布尔值参数 ParamTypeInt 整数参数 ParamTypeFloat 浮点数参数 ParamTypeString 字符串参数 ParamTypeActor 实体目标选择器参数 ParamTypePlayer 玩家目标选择器参数 ParamTypeBlockPos 整数坐标参数 ParamTypeVec3 浮点数坐标参数 ParamTypeRawText 原始字符串参数可包含特殊字符如逗号空格只能作为最后一个参数使用 ParamTypeMessage 消息类型参数同 say 指令参数会自动展开目标选择器等 ParamTypeJsonValue JSON字符串参数 ParamTypeItem 物品类型参数 ParamTypeBlock 方块类型参数 ParamTypeEffect 效果类型参数 ParamTypeEnum 枚举参数 ParamTypeSoftEnum 可变枚举参数 ParamTypeActorType 实体类型参数 ParamTypeCommand 指令名称参数仅供测试 新增一条指令重载要想让命令正常运行必须至少添加一条重载。所谓重载本质上相当于参数的组合譬如重载a b c相当于命令可以被执行为cmd a b c而重载相当于可以被执行为cmd。重载的参数标识符可以是参数名、枚举名、参数标识符但不能使用无法区分具体参数的标识符如两个参数都叫action 但枚举选项不同此时应该使用枚举名而不是参数名。Commandoverloadparams参数标识符重载所用到的参数列表可用 参数标识符、枚举名、参数名。 注意不能使用无法区分具体参数的标识符如两个参数都叫 action 但枚举选项不同此时应该使用枚举名而不是参数名 tip指令重载是 BDS 区分不同指令形式的方法每一种不同的指令形式对应着一种指令重载。 如你所见指令重载中提供的各项参数名组成了一种新的指令形式设置指令回调CommandsetCallbackcallback注册的这个命令被执行时接口自动调用的回调函数。 tip指令回调函数的参数相对复杂在下面将进行详细解释安装指令在对命令的所有配置完成之后使用此函数将命令注册到 BDS 的命令系统当中Commandsetup指令回调函数上文提到的 指令回调函数 是一个比较复杂的回调函数下面对其中的各项参数进行一些解释 指令回调函数原型 Functioncmdoriginoutputresults参数 cmd 自身的指令对象这个参数给出了你注册这个命令时使用的指令对象。参数 origin 命令的执行者参数 origin的类型为 CommandOrigin 对象。此对象表示此次命令的执行者通过这个对象可以对执行者进行一些操作 对于某个特定的 CommandOrigin 对象ori有以下这些属性 属性 含义 类型 oritype 指令执行主体类型 OriginType oriname 指令执行主体的名称 String oripos 指令执行主体的坐标 FloatPos oriblockPos 指令执行主体的方块坐标 IntPos orientity 执行指令的实体可空 Entity oriplayer 执行指令的玩家可空 Player 参数 output 向命令执行者输出命令的执行结果参数output的类型为CommandOutput 对象。通过这个对象可以向命令执行者输出命令的执行结果。 对于某个特定的 CommandOutput 对象outp有以下这些成员方法输出一条成功信息outpsuccessmsg parm要输出的信息要替换的参数输出一条错误信息outperrormsg parm要输出的信息要替换的参数输出一条普通信息outpaddMessagemsg parm要输出的信息要替换的参数参数 result 命令各项参数获取的结果results 的内容为 object命令参数名数据值 键值对。其中 命令参数名 为命令注册时设置的参数的 name值而数据值即为执行者在当前命令参数的位置填上的内容命令参数类型 和 数据值类型 的对应关系如下 命令参数类型 数据值类型 含义 ParamTypeBool Boolean 布尔值 ParamTypeInt Integer 整数 ParamTypeFloat Float 浮点数 ParamTypeString String 字符串 ParamTypeActor ArrayActor 实体目标选择器 选中的实体 ParamTypePlayer ArrayPlayer 玩家目标选择器 选中的实体 ParamTypeBlockPos IntPos 整数坐标对象 ParamTypeVec3 FloatPos 浮点数坐标对象 ParamTypeRawText String 原始字符串可包含特殊字符如逗号空格只能作为最后一个参数使用 ParamTypeMessage String 消息类型字符串同 say 指令参数会自动展开目标选择器等 ParamTypeJsonValue String JSON字符串 ParamTypeItem Item 物品类型 ParamTypeBlock Block 方块类型 ParamTypeEffect String 效果类型字符串 ParamTypeEnum String 枚举字符串 ParamTypeSoftEnum String 可变枚举字符串 ParamTypeActorType String 实体类型字符串 ParamTypeCommand String 指令名称仅供测试 命令注册样例JavaScriptjsmclistenonServerStarted const cmd mcnewCommandmanager Command Description PermTypeGameMasterscmdsetAliasmgrcmdsetEnumChangeAction add removecmdsetEnumListAction listcmdmandatoryaction ParamTypeEnum ChangeAction 1cmdmandatoryaction ParamTypeEnum ListAction 1cmdmandatoryname ParamTypeRawTextcmdoverloadChangeAction namecmdoverloadListActioncmdsetCallbackcmd ori out res switch resaction case addreturn outsuccessadd resnamecase removereturn outsuccessremove resnamecase listreturn outsuccessName Listcmdsetup假命令 API这里的假命令API为 向下兼容 而留存推荐使用上面文档所写的的 真命令 API warning尽管看起来比较简单但是假命令有一些很重要的缺点包括只能由玩家或控制台执行其他对象如命令方块、NPC等都无法执行、所有参数数据都需要自行解析等等。请尽量使用 真命令API注册一个新的玩家命令假命令mcregPlayerCmdcmddescriptioncallbacklevel待注册的命令命令描述文本注册的这个命令被执行时接口自动调用的回调函数。可选参数命令的注册等级默认为 0 即所有人都可以执行 如果设置命令注册等级为1则只有OP可以执行此命令注参数callback的回调函数原型functionplayerargs执行命令的玩家对象目标命令后面的参数。按空格为分界分割组成字符串数组。 如注册了自定义命令 land set当执行 land set abc 2333 时args的值将为 abc2333 JavaScriptjsmcregPlayerCmdfly on Turn on the fly mode function pl args pltellFlying enabled注册一个新的控制台命令假命令mcregConsoleCmdcmddescriptioncallback待注册的命令命令描述文本注册的这个命令被执行时接口自动调用的回调函数。注参数callback的回调函数原型functionargs目标命令后面的参数。按空格为分界分割组成字符串数组。 如注册了自定义命令 land set当执行 land set abc 2333 时args的值将为 abc2333JavaScriptjsmcregConsoleCmdbackup Start the backup function args logID of this backup is args0 tip 假命令注册相关说明设置了回调函数之后在你注册的这个假命令被执行的时候回调函数就会被调用。 在调用之前脚本引擎会自动帮你把命令参数分割成数组。 以JavaScript语言为例执行命令 mcregPlayerCmdland buy 购买领地 functionplargs 0 之后 当你使用命令 land buy abcde 12345的时候这个回调函数就会被调用。 回调函数的参数args被传入一个数组 abcde 12345 正如所见args 中包含的值是被 按顺序分割好的 命令参数。 如果你的命令中有引号比如说为了处理含有空格的玩家名字脚本引擎在分割时也会做处理。其他与命令系统有关的 API模拟产生一个控制台命令输出mcsendCmdOutputoutput模拟产生的命令输出 容器对象 API在脚本引擎中使用「容器对象」来操作拥有格子、可以储存和放置物品的容器的相关信息。 此处的 容器 是一种宽泛的概念除了箱子、桶这些传统的容器之外如玩家物品栏、羊驼携带的箱子等这些也统统可以作为「容器」处理获取并使用容器对应的API获取一个容器对象从事件或API获取通过注册事件监听函数或者调用某些返回容器对象的函数来获取到BDS给出的容器对象 详见 事件监听文档 EventAPIEventAPIListenzhmd 通过实体获取通过玩家对象的各个成员函数来获取一个玩家物品栏、盔甲栏、末影箱对应的容器对象 详见 玩家对象 APIPlayerzhmd 通过方块获取对于可以容纳物品的方块通过方块对象的成员函数来他所对应的对应的容器对象 详见 方块对象 APIBlockzhmd 注意不要长期保存一个容器对象 当容器对象对应的实体 方块被销毁时对应的容器对象将同时释放。因此如果有长期操作某个容器的需要请通过上述途径获取实时的容器对象容器信息对象 属性每一个容器信息对象都包含一些固定的对象属性。对于某个特定的容器对象ct有以下这些属性 属性 含义 类型 ctsize 容器拥有的格子总数 Integer cttype 容器的类型名 String 容器对象 函数每一个容器对象都包含一些可以执行的成员函数成员方法。对于某个特定的容器对象ct可以通过以下这些函数对这个容器进行一些操作 注意在修改完玩家物品栏对应的物品之后不要忘记使用玩家对象的成员函数plrefreshItems刷新客户端显示的玩家物品栏放入物品对象到容器中 ctaddItemitem amount 待增加的物品对象可选欲添加物品数量若提供此参数item对象本身的count属性将被忽略。放入物品对象到容器的第一个空格子ctaddItemToFirstEmptySlotitem 待增加的物品对象和上述函数不同此函数将不会堆叠至容器内现有的物品堆中检查容器中是否有空间可以放入此物品 cthasRoomForitem 待放入的物品对象减少容器中的某个物品对象ctremoveItemindexcount 减少的物品对象所在的格子序号减少的数量。如果大于等于此格子物品堆叠的数量则物品堆将被整个清除获取容器某个格子的物品对象ctgetItemindex 待获取的格子序号此处获取的物品对象为引用。也就是说修改此处返回的物品对象或使用其API就相当于直接操作容器中对应的物品设置容器某个格子的物品对象ctsetItemindexitem 待设置的格子序号待设置的物品对象获取容器所有格子的物品对象列表ctgetAllItems 此处获取的物品对象均为引用。也就是说修改此处返回的物品对象或使用其API就相当于直接操作容器中对应的物品清空容器ctremoveAllItems 判断容器是否为空ctisEmpty 设备信息对象 API在脚本引擎中使用「设备信息对象」来操作和获取某一个玩家使用的游戏设备的相关信息。获取一个设备信息对象通过玩家获取通过玩家对象的getDevice成员函数来获取一个玩家对应的设备信息对象 详见 玩家对象 APIPlayerzhmd 注意不要长期保存一个设备信息对象 当设备对应的玩家退出游戏时对应的对象将同时释放。因此如果有长期操作某个对象的需要请通过上述途径获取实时的设备信息对象设备信息对象 属性每一个设备信息对象都包含一些固定的对象属性。对于某个特定的实体对象dv有以下这些属性 属性 含义 类型 dvip 玩家设备的IP地址 String dvavgPing 玩家的平均网络延迟时间ms Integer dvavgPacketLoss 玩家的平均网络丢包率 Float dvlastPing 玩家的网络延迟时间ms Integer dvlastPacketLoss 玩家的网络丢包率 Float dvos 玩家设备的操作系统类型 String dvinputMode 玩家的操作模式 Integer dvserverAddress 玩家连接的地址 String dvclientId 玩家客户端的识别码ID String 这些对象属性都是只读的无法被修改 其中操作系统类型属性返回一个字符串记录了玩家设备的操作系统。可能返回的值如下表 dvos返回字符串 玩家设备的操作系统 Android 手机谷歌Android iOS 手机苹果iOS平板iPadOS OSX 电脑苹果macOS Amazon 平板电视亚马逊FireOS GearVR 头显三星GearVR Hololens 头显微软HoloLens Windows10 电脑微软Windows Win32 电脑微软Win32教育版 TVOS 机顶盒苹果tvOS PlayStation 主机索尼PlayStation Nintendo 掌机任天堂Switch Xbox 主机微软Xbox WindowsPhone 手机微软Windows Mobile Unknown 未知系统 Input mode ENUM 备注 InputModeMouse 鼠标 InputModeTouch 触屏 InputModeGamePad 手柄 InputModeMotionController 运动控制器 实体对象 API在脚本引擎中使用「实体对象」来操作和获取某一个实体的相关信息。获取一个实体对象从事件或API获取通过注册事件监听函数或者调用某些返回实体对象的函数来获取到BDS给出的实体对象 详见 事件监听文档 EventAPIEventAPIListenzhmd获取当前所有已加载的实体此函数会返回一个实体对象的数组其中每个对象都对应了一个已加载的实体mcgetAllEntities获取在特定范围内的实体mcgetEntitiesstartPosrange mcgetEntitiesstartPosendPosrange搜索的起始坐标搜索的终止坐标搜索范围从现有实体获取通过实体信息手动生成实体对象 通过此函数来手动生成对象注意你要获取的实体必须是在线状态否则会生成失败 warning此函数仅在095及以后版本可用mcgetEntityinfo实体的UniqueId或者RuntimeId生成新生物并获取通过此函数在指定的位置生成一个新生物并获取它对应的实体对象mcspawnMobnamepos mcspawnMobnamexyzdimid生物的命名空间名称如 minecraftcreeper生成生物的位置的坐标对象或者使用x y z dimid来确定生成位置 注意不要长期保存一个实体对象 当实体对象对应的实体被销毁时对应的实体对象将同时释放。因此如果有长期操作某个实体的需要请通过上述途径获取实时的实体对象复制生物并获取通过此函数在指定的位置复制另一个实体并获取它对应的实体对象mccloneMobentitypos mccloneMobentityxyzdimid需要复制的实体对象生成生物的位置的坐标对象或者使用x y z dimid来确定生成位置 注意不要长期保存一个实体对象 当实体对象对应的实体被销毁时对应的实体对象将同时释放。因此如果有长期操作某个实体的需要请通过上述途径获取实时的实体对象实体对象 属性每一个实体对象都包含一些固定的对象属性。对于某个特定的实体对象en有以下这些属性 属性 含义 类型 enname 实体名称 String entype 实体标准类型名 String enid 实体的游戏内 id Integer enpos 实体所在坐标 FloatPos enfeetPos 实体腿部所在坐标 FloatPos enblockPos 实体所在的方块坐标 IntPos enmaxHealth 实体最大生命值 Integer enhealth 实体当前生命值 Integer encanFly 实体是否能飞行 Boolean encanFreeze 实体是否能被冻结 Boolean encanSeeDaylight 实体是否能看到天空 Boolean encanPickupItems 实体是否能拾取物品 Boolean eninAir 实体是否悬空 Boolean eninWater 实体是否在水中 Boolean eninLava 实体是否在岩浆中 Boolean eninRain 实体是否在雨中 Boolean eninSnow 实体是否在雪中 Boolean eninWall 实体是否在墙上 Boolean eninWaterOrRain 实体是否在水中或雨中 Boolean eninWorld 实体是否在世界中 Boolean enspeed 实体当前速度 Float endirection 实体当前朝向 DirectionAngle enuniqueId 实体唯一标识符 String enruntimeId 实体运行时标识符在 095 时被加入 String enisInvisible 实体是否不可见 Boolean enisInsidePortal 实体是否在门户内 Boolean enisTrusting 实体是否信任 Boolean enisTouchingDamageBlock 实体是否接触到伤害方块 Boolean enisOnFire 实体是否着火 Boolean enisOnGround 实体是否在地面 Boolean enisOnHotBlock 实体是否在热块上 Boolean enisTrading 实体是否在交易 Boolean enisRiding 实体是否正在骑行 Boolean enisDancing 实体是否在跳舞 Boolean enisSleeping 实体是否在睡觉 Boolean enisAngry 实体是否生气 Boolean enisBaby 实体是否为幼体 Boolean enisMoving 实体是否移动 Boolean 这些对象属性都是只读的无法被修改实体对象 函数每一个实体对象都包含一些可以执行的成员函数成员方法。对于某个特定的实体对象en可以通过以下这些函数对这个实体进行一些操作传送实体至指定位置enteleportposrot enteleportxyzdimidrot目标位置坐标或者使用x y z dimid来确定实体位置可选参数传送后实体的朝向若缺省则与传送前朝向相同杀死指定实体enkill使指定实体刷新消失endespawn移除指定实体enremove对实体造成伤害enhurtdamagetypesource对实体造成的伤害数值伤害类型伤害来源注意此处造成的伤害为真实伤害无法被盔甲等保护装备减免 ActorDamageCause 枚举 值 ActorDamageCauseNone 1 ActorDamageCauseOverride 0 ActorDamageCauseContact 1 ActorDamageCauseEntityAttack 2 ActorDamageCauseProjectile 3 ActorDamageCauseSuffocation 4 ActorDamageCauseFall 5 ActorDamageCauseFire 6 ActorDamageCauseFireTick 7 ActorDamageCauseLava 8 ActorDamageCauseDrowning 9 ActorDamageCauseBlockExplosion 10 ActorDamageCauseEntityExplosion 11 ActorDamageCauseVoid 12 ActorDamageCauseSelfDestruct 13 ActorDamageCauseMagic 14 ActorDamageCauseWither 15 ActorDamageCauseStarve 16 ActorDamageCauseAnvil 17 ActorDamageCauseThorns 18 ActorDamageCauseFallingBlock 19 ActorDamageCausePiston 20 ActorDamageCauseFlyIntoWall 21 ActorDamageCauseMagma 22 ActorDamageCauseFireworks 23 ActorDamageCauseLightning 24 ActorDamageCauseCharging 25 ActorDamageCauseTemperature 26 ActorDamageCauseFreezing 27 ActorDamageCauseStalactite 28 ActorDamageCauseStalagmite 29 ActorDamageCauseRamAttack 30 ActorDamageCauseSonicBoom 31 ActorDamageCauseCampfire 32 ActorDamageCauseSoulCampfire 33 ActorDamageCauseMaceSmash 34 ActorDamageCauseAll 35 治疗实体enhealhealth治疗的心数设置实体的生命值ensetHealthhealth生命值数为实体设置伤害吸收属性ensetAbsorptionvalue新的值为实体设置攻击伤害属性ensetAttackDamagevalue新的值为实体设置最大攻击伤害属性ensetMaxAttackDamagevalue新的值为实体设置跟随范围ensetFollowRangevalue新的值为实体设置击退抵抗属性ensetKnockbackResistancevalue新的值 0 or 1为实体设置幸运属性ensetLuckvalue新的值为实体设置移动速度属性ensetMovementSpeedvalue新的值为实体设置水下移动速度属性ensetUnderwaterMovementSpeedvalue新的值为实体设置岩浆上移动速度属性ensetLavaMovementSpeedvalue新的值设置实体的最大生命值ensetMaxHealthhealth生命值数设置特定实体为燃烧状态ensetFiretime isEffect燃烧的时间秒为单位是否有火焰效果熄灭实体enstopFire缩放实体ensetScalescale新的实体体积获取实体到坐标的距离endistanceToposendistanceToSqrpos目标位置 注意 若玩家的坐标与目标的坐标不在同一维度将返回整数最大值。判断一个实体对象是不是玩家enisPlayer将实体对象转换玩家对象entoPlayer如果当前实体对象指向的是一个玩家可以使用此函数将实体对象转换为玩家对象以使用更多的玩家相关 API判断一个实体对象是不是掉落物实体enisItemEntity获取掉落物实体中的物品对象entoItem如果当前实体对象是一个掉落物实体可以使用此函数获取掉落物实体中的物品对象以使用更多的物品相关 API获取实体当前站立所在的方块engetBlockStandingOn获取生物盔甲栏的容器对象engetArmor关于容器对象的更多使用请参考 容器对象 API文档Containerzhmd判断生物是否拥有容器盔甲栏除外enhasContainer如羊驼身上的箱子等他们各自拥有一个属于自己的容器对象获取生物所拥有的容器对象盔甲栏除外engetContainer关于容器对象的更多使用请参考 容器对象 API文档Containerzhmd刷新生物物品栏、盔甲栏enrefreshItems在修改生物物品之后为了促使客户端生效需要刷新生物所有的物品为实体增加一个TagenaddTagtag要增加的tag字符串为实体移除一个TagenremoveTagtag要移除的tag字符串检查实体是否拥有某个TagenhasTagtag要检查的tag字符串返回实体拥有的所有Tag列表engetAllTags获取实体对应的NBT对象engetNbt写入实体对应的NBT对象ensetNbtnbtNBT对象关于NBT对象的更多使用请参考 NBT接口文档NbtAPINBTmd获取视线方向实体engetEntityFromViewVectormaxDistance查找最大距离获取视线方向方块engetBlockFromViewVectorincludeLiquidsolidOnlymaxDistancefullOnly是否包含液态方块是否仅允许 Solid 类型的方块查找最大距离是否仅允许完整方块获取生物所在群系IDengetBiomeId获取生物所在群系名称engetBiomeName获取实体全部药水效果engetAllEffects为实体添加一个药水效果enaddEffectid tick level showParticles药水效果的id见下表持续时间等级是否显示粒子为实体移除一个药水效果enremoveEffectid药水效果的id见下表 效果 名称 数字id 迅捷 speed 1 缓慢 slowness 2 急迫 haste 3 挖掘疲劳 miningfatigue 4 力量 strength 5 瞬间治疗 instanthealth 6 瞬间伤害 instantdamage 7 跳跃提升 jumpboost 8 反胃 nausea 9 生命恢复 regeneration 10 抗性提升 resistance 11 抗火 fireresistance 12 水下呼吸 waterbreathing 13 隐身 invisibility 14 失明 blindness 15 夜视 nightvision 16 饥饿 hunger 17 虚弱 weakness 18 中毒 poison 19 凋零 wither 20 生命提升 healthboost 21 伤害吸收 absorption 22 饱和 saturation 23 飘浮 levitation 24 中毒致命 fatalpoison 25 潮涌能量 conduitpower 26 缓降 slowfalling 27 不祥之兆 badomen 28 村庄英雄 villagehero 29 黑暗 darkness 30 其他实体函数 API下面这些API提供了与游戏中指定位置实体互动的API在指定位置制造一次爆炸mcexplodepossourcemaxResistanceradiusisDestroyisFire mcexplodexyzdimidsourcemaxResistanceradiusisDestroyisFire引发爆炸的位置坐标或者使用x y z dimid来确定实体位置设置爆炸来源的实体对象可以为Null方块最大爆炸抗性低于此值的方块会被破坏爆炸的范围半径影响爆炸的波及范围爆炸是否破坏方块爆炸结束后是否留下燃烧的火焰快速执行Molang表达式enquickEvalMolangScriptstrMolang表达式关于Molang的详细使用方法请参考 MOLANG文档 bedrockdevhttpsbedrockdevzhdocsstableMolang 游戏实用工具 API下面这些API提供了某些帮助游戏内容开发的实用工具接口让开发效率可以得到一定的提高。格式化代码实用工具MC通过 格式化代码 符号在游戏内提供颜色文字、样式修改等格式控制能力。格式化代码分为颜色代码与格式代码两种分别提供颜色控制和样式控制两种能力。 此处的接口为了帮助开发者快速上手MC格式化代码而不需要频繁查表才能使用 注意此处接口仅有在传递到BDS中并显示时才会产生效果颜色代码表 颜色代码符号 表示的颜色意义 游戏内对应的字符串 FormatBlack 接下来的文字为 黑色 0 FormatDarkBlue 接下来的文字为 深蓝色 1 FormatDarkGreen 接下来的文字为 深绿色 2 FormatDarkAqua	 接下来的文字为 湖蓝色 3 FormatDarkRed 接下来的文字为 深红色 4 FormatDarkPurple 接下来的文字为 紫色 5 FormatGold 接下来的文字为 金色 6 FormatGray 接下来的文字为 灰色 7 FormatDarkGray 接下来的文字为 深灰色 8 FormatBlue 接下来的文字为 蓝色 9 FormatGreen 接下来的文字为 浅绿色 a FormatAqua 接下来的文字为 天蓝色 b FormatRed 接下来的文字为 浅红色 c FormatLightPurple 接下来的文字为 浅紫色 d FormatYellow 接下来的文字为 浅黄色 e FormatWhite 接下来的文字为 白色 f FormatMinecoinGold	 接下来的文字为 硬币金色 g 格式代码表 格式代码符号 表示的格式意义 游戏内对应的字符串 FormatBold 接下来的文字 加粗 l FormatItalics 接下来的文字 斜体 o FormatUnderline 接下来的文字 u下划线u n FormatStrikeThrough 接下来的文字 删除线 m FormatRandom 接下来的文字 随机闪烁的乱码字符 k FormatClear 接下来的文字 清除所有格式 r 上述代码使用的方法为连接字符串类似于JavaScriptjsmcbroadcastFormatRed FormatBold Red Bold FormatDarkGreen FormatUnderline DarkGreen Underline FormatClear ClearLualuamcbroadcastFormatRed FormatBold Red Bold FormatDarkGreen FormatUnderline DarkGreen Underline FormatClear Clear 物品对象 API在脚本引擎中使用「物品对象」来操作和获取某一个物品栏物品的相关信息。获取一个物品对象从事件或API获取通过注册事件监听函数或者调用某些返回物品对象的函数来获取到BDS给出的物品对象 详见 事件监听文档 EventAPI EventAPIListenzhmd 生成新的物品对象通过此函数根据给出的信息生成一个新的物品对象mcnewItemnamecount 物品的标准类型名如minecraftbread物品堆叠数量由于 unsigned int8最大值为 64从现有的物品对象克隆通过此函数根据某个现有的物品对象克隆一个新的物品对象 新的物品对象与旧的对象并无关联关系 对于一个已经存在的物品对象item有函数itemclone 通过 NBT 生成物品对象通过此函数根据某个NBT生成一个新的物品对象mcnewItemnbt 生成物品对象所使用的物品NBT 注意不要长期保存一个物品对象 当物品对象对应的物品被销毁时对应的物品对象将同时释放。因此如果有长期操作某个物品的需要请通过上述途径获取实时的物品对象物品对象 属性每一个物品对象都包含一些固定的对象属性。对于某个特定的物品对象it有以下这些属性 属性 含义 类型 itname 游戏内显示的物品名称 String ittype 物品标准类型名 String itid 物品的游戏内 id Integer itcount 这个物品对象堆叠的个数 Integer itmaxCount 这个物品对象堆叠的最大个数在 0161 时被加入 Integer itaux 物品附加值如羊毛颜色 Integer itdamage 物品已消耗耐久 Integer itattackDamage 物品攻击伤害 Integer itmaxDamage 物品最大耐久 Integer itlore 物品 Lore ArrayString String itisArmorItem 物品是否为盔甲 Boolean itisBlock 物品是否为方块 Boolean itisDamageableItem 物品是否可被破坏 Boolean itisDamaged 物品耐久是否被消耗 Boolean itisEnchanted 物品是否已被附魔 Boolean itisEnchantingBook 物品是否为附魔书 Boolean itisFireResistant 物品是否防火 Boolean itisFullStack 物品是否已堆叠到最大堆叠数 Boolean itisGlint 物品是否闪烁 Boolean itisHorseArmorItem 物品是否为马铠 Boolean itisLiquidClipItem Whether the item is liquid clip Boolean itisMusicDiscItem 物品是否为唱片 Boolean itisOffhandItem 物品是否可设置到副手 Boolean itisPotionItem 物品是否为药水 Boolean itisStackable 物品是否可堆叠 Boolean itisWearableItem 物品是否可穿戴 Boolean 这些对象属性都是只读的无法被修改物品对象 函数每一个物品对象都包含一些可以执行的成员函数成员方法。对于某个特定的物品对象it可以通过以下这些函数对这个物品进行一些操作 注意在修改完玩家物品栏对应的物品之后不要忘记使用玩家对象的成员函数plrefreshItems刷新客户端显示的玩家物品栏判断物品对象是否为空itisNull比如说当某个格子没有任何物品的时候你获取到的物品对象即是空将此物品对象置为空删除物品itsetNull将此物品对象设置为另一个物品itsetitem要赋值的物品对象设置物品耐久度itsetDamagedamage耐久度设置物品的附加值itsetAuxaux物品附加值根据物品对象生成掉落物实体通过此函数根据物品对象在指定的位置生成一个同样内容的掉落物实体mcspawnItemitempos mcspawnItemitemxyzdimid 生成掉落物实体所使用的物品对象生成掉落物实体的位置的坐标对象或者使用x y z dimid来确定生成位置获取物品对应的NBT对象itgetNbt写入物品对应的NBT对象itsetNbtnbtNBT对象关于NBT对象的更多使用请参考 NBT接口文档NbtAPINBTmd设置自定义LoreitsetLorenames要设置的Lore字符串的数组设置自定义物品名称itsetDisplayNamename新物品名称判断是否为同类物品itmatchitem被判断的物品 数据包 API下面这些对象与API为脚本提供了基本的BDS数据包接口。 温馨提示此类API需要部分逆向基础了解数据包结构可通过参考NukkitPokcetMineBDS逆向得知数据包结构如出现客户端崩溃为数据包结构错误并非BUG。 文档不列出数据包ID与其结构请自行查询。目录 数据包对象 API在脚本引擎中使用「数据包对象」来获取数据包的相关信息。获取一个数据包对象从API获取调用某些返回数据包对象的函数来获取到BDS给出的数据包对象 详见 二进制流对象二进制流对象api 数据包对象 函数每一个数据包对象都包含一些可以执行的成员函数成员方法。对于某个特定的实体对象pkt可以通过以下这些函数对这个数据包进行一些操作获取数据包名称pktgetName获取数据包IDpktgetId 二进制流对象 API创建一个二进制流对象JavaScript new BinaryStreamLua BinaryStream二进制流对象 函数每一个二进制流对象都包含一些可以执行的成员函数成员方法。对于某个特定的实体对象bs可以通过以下这些函数对这个二进制流进行一些操作重置二进制流bsreset写入二进制流bswritexxxxvalue 参考下面表格 可用函数 参数类型 writeBool Boolean writeByte Integer writeDouble Number writeFloat Float writeSignedBigEndianInt Number writeSignedInt Number writeSignedInt64 Number writeSignedShort Integer writeString String writeUnsignedChar Integer writeUnsignedInt Number writeUnsignedInt64 Number writeUnsignedShort Integer writeUnsignedVarInt Number writeUnsignedVarInt64 Number writeVarInt Number writeVarInt64 Number writeVec3 FloatPos writeBlockPos 095 时加入 BlockPos writeCompoundTag NbtCompound writeItem 095 时加入 Item 通过二进制流构建数据包bscreatePacketpktid 数据包ID演示代码向一个玩家发送TextPacket数据包jsmclistenonChatfunctionplmsgconst bs new BinaryStreamvar text LLSE Packet Testbsreservetextlength 8bswriteUnsignedChar0bswriteBooltruebswriteStringtextbswriteStringbswriteStringvar pkt bscreatePacket9plsendPacketpkt ParticleSpawner 对象 warningParticleSpawner已在0150中废弃除了spawnParticle外的所有API均不可用。对于某个 ParticleSpawner 类型变量 ps 有如下这些成员 成员 含义 类型 psdisplayRadius 粒子显示半径 Integer pshighDetial 需要高细节线条 Boolean psdoubleSide 需要双面粒子 Boolean 生成一个粒子生成器对象mcnewParticleSpawnerdisplayRadius 4294967295 highDetial true doubleSide true粒子颜色枚举 粒子颜色枚举 ParticleColorBlack ParticleColorIndigo ParticleColorLavender ParticleColorTeal ParticleColorCocoa ParticleColorDark ParticleColorOatmeal ParticleColorWhite ParticleColorRed ParticleColorApricot ParticleColorYellow ParticleColorGreen ParticleColorVatblue ParticleColorSlate ParticleColorPink ParticleColorFawn 方向枚举 方向枚举 DirectionNEGY DirectionPOSY DirectionNEGZ DirectionPOSZ DirectionNEGX DirectionPOSX 生成指定名称粒子psspawnParticlepos name 以下粒子均为 2s 显示时间生成点粒子psdrawPointpos pointSize 4 color ParticleColorWhite生成数字粒子psdrawNumberpos num color ParticleColorWhite生成轴向线段psdrawAxialLinepos direction length color ParticleColorWhite生成有向线段psdrawOrientedLinestart end lineWidth 4 minSpacing 1 maxParticlesNum 64 color ParticleColorWhite生成圆psdrawCirclepos facing radius lineWidth 4 minSpacing 1 maxParticlesNum 64 color ParticleColorWhite生成立方体psdrawCuboidpospos2 color ParticleColorWhite 玩家对象 API在脚本引擎中使用「玩家对象」来操作和获取某一个玩家的相关信息。获取一个玩家对象从事件或API获取通过注册事件监听函数获取到BDS给出的与相关事件有关的玩家对象 详见 事件监听文档 EventAPIEventAPIListenzhmd从现有玩家获取通过玩家信息手动生成玩家对象 通过此函数来手动生成对象注意你要获取的玩家必须是在线状态否则会生成失败mcgetPlayerinfo warning0813之前的版本无法使用UUID获取玩家 095之前的版本无法使用RuntimeId获取玩家玩家的名字、XUID、UniqueId、RuntimeId或者UUID获取所有在线玩家此函数会返回一个玩家对象的数组其中每个对象都对应了一个服务器中的玩家mcgetOnlinePlayers 注意不要长期保存一个玩家对象 当玩家退出服务器时对应的玩家对象将同时释放。因此如果有长期操作某个玩家的需要请通过上述途径获取实时的玩家对象玩家对象 属性每一个玩家对象都包含一些固定的对象属性。对于某个特定的玩家对象pl有以下这些属性 属性 含义 类型 plname 玩家名 String plpos 玩家所在坐标 FloatPos plfeetPos 玩家腿部所在坐标 FloatPos plblockPos 玩家所在的方块坐标 IntPos pllastDeathPos 玩家上次死亡的坐标 IntPos plrealName 玩家的真实名字 String plxuid 玩家 XUID 字符串 String pluuid 玩家 Uuid 字符串 String plpermLevel 玩家的操作权限等级0 4 Integer plgameMode 玩家的游戏模式0 2 6 Integer plcanFly 玩家是否可以飞行 Boolean plcanSleep 玩家是否可以睡觉 Boolean plcanBeSeenOnMap 玩家是否可以在地图上看到 Boolean plcanFreeze 玩家是否可以冻结 Boolean plcanSeeDaylight 玩家是否能看到日光 Boolean plcanShowNameTag 玩家是否可以显示姓名标签 Boolean plcanStartSleepInBed 玩家是否可以开始在床上睡觉 Boolean plcanPickupItems 玩家是否可以拾取物品 Boolean plmaxHealth 玩家最大生命值 Integer plhealth 玩家当前生命值 Integer plinAir 玩家当前是否悬空 Boolean plinWater 玩家当前是否在水中 Boolean plinLava 玩家是否在熔岩中 Boolean plinRain 玩家是否下雨 Boolean plinSnow 玩家是否在雪中 Boolean plinWall 玩家是否在墙上 Boolean plinWaterOrRain 玩家是否在水中或雨中 Boolean plinWorld 玩家是否在世界 Boolean plinClouds 玩家是否在云端 Boolean plspeed 玩家当前速度 Float pldirection 玩家当前朝向 DirectionAngle pluniqueId 玩家实体的唯一标识符 String plruntimeId 玩家实体的运行时标识符在 095 时被加入 String pllangCode 玩家设置的语言的标识符形如 zhCN String plisLoading 玩家是否正在加载 Boolean plisInvisible 玩家是否隐身中 Boolean plisInsidePortal 玩家在传送门中 Boolean plisHurt 玩家是否受伤 Boolean plisTrusting 未知 Boolean plisTouchingDamageBlock 玩家是否在能造成伤害的方块上 Boolean plisHungry 玩家是否饿了 Boolean plisOnFire 玩家是否着火 Boolean plisOnGround 玩家是否在地上 Boolean plisOnHotBlock 玩家是否在高温方块上岩浆等 Boolean plisTrading 玩家在交易 Boolean plisAdventure 玩家是否是冒险模式 Boolean plisGliding 玩家在滑行 Boolean plisSurvival 玩家是否是生存模式 Boolean plisSpectator 玩家是否是观众模式 Boolean plisRiding 玩家是否在骑行 Boolean plisDancing 玩家在跳舞 Boolean plisCreative 玩家是否是创造模式 Boolean plisFlying 玩家是否在飞行 Boolean plisSleeping 玩家是否正在睡觉 Boolean plisMoving 玩家是否正在移动 Boolean plisSneaking 玩家是否正在潜行 Boolean 这些对象属性都是只读的无法被修改。其中 操作权限等级 对应操作权限 0 普通成员权限 1 OP权限 4 OP 控制台权限 玩家对象 函数每一个玩家对象都包含一些可以执行的成员函数成员方法。对于某个特定的玩家对象pl可以通过以下这些函数对这个玩家进行一些操作判断玩家是否为OPplisOPjs 对于一个玩家对象plvar open plisOPluaopen plisOP断开玩家连接plkickmsg pldisconnectmsg可选参数被踢出玩家出显示的断开原因。 如果不传入默认为正在从服务器断开连接js 对于一个玩家对象plplkickluaplkick发送一个文本消息给玩家pltellmsgtype plsendTextmsgtype待发送的文本可选参数发送的文本消息类型默认为0 type参数 消息类型 0 普通消息Raw 1 聊天消息Chat 4 音乐盒消息Popup 5 物品栏上方的消息Tip 9 JSON格式消息JSON js对于一个玩家对象plpltellWelcome back 5luapltellWelcome back 5设置玩家显示标题plsetTitlecontenttypefadeInTimestayTimefadeOutTime欲设置标题内容可选参数设置的标题类型默认为2 type参数 消息类型 0 清空Clear 1 重设Reset 2 设置主标题SetTitle 3 设置副标题SetSubTitle 4 设置ActionbarSetActionBar 5 设置显示时间SetDurations 6 Json型主标题TitleTextObject 7 Json型副标题SubtitleTextObject 8 Json型ActionbarActionbarTextObject 可选参数淡入时间单位为 Tick 默认为10可选参数停留时间单位为 Tick 默认为70可选参数淡出时间单位为 Tick默认为20广播一个文本消息给所有玩家mcbroadcastmsgtype待发送的文本可选参数发送的文本消息类型默认为0 type参数 消息类型 0 普通消息Raw 1 聊天消息Chat 5 物品栏上方的消息Tip 9 JSON格式消息JSON js 对于一个玩家对象plmcbroadcastHello everyone luamcbroadcastHello everyone 在屏幕上方显示消息类似于成就完成plsendToasttitlemessage待发送的标题待发送的文本js 对于一个玩家对象plplsendToastHello everyone luaplsendToastHello everyone 以某个玩家身份执行一条命令plruncmdcmd待执行的命令js 对于一个玩家对象plplruncmdtp 50 luaplruncmdtp 50 以某个玩家身份说话pltalkAstext模拟说话内容js 对于一个玩家对象plpltalkAsHello everyone luapltalkAsHello everyone 获取玩家到坐标的距离pldistanceTopospldistanceToSqrpos目标位置 注意 若玩家的坐标与目标的坐标不在同一维度将返回整数最大值。以某个玩家身份向某玩家说话pltalkTotexttarget模拟说话内容模拟说话对象js 对于一个玩家对象plpltalkAsanotherpl Hello luapltalkAsanotherpl Hello everyone 传送玩家至指定位置plteleportposrotplteleportxyzdimidrot目标位置坐标 或者使用x y z dimid来确定玩家位置可选参数传送后玩家的朝向若缺省则与传送前朝向相同js对于一个玩家对象plplteleportposluaplteleportpos杀死玩家plkilljs 对于一个玩家对象plplkillluaplkill对玩家造成伤害plhurtdamagetypesource对玩家造成的伤害数值伤害类型伤害来源注意此处造成的伤害为真实伤害无法被盔甲等保护装备减免 ActorDamageCause 枚举 值 ActorDamageCauseNone 1 ActorDamageCauseOverride 0 ActorDamageCauseContact 1 ActorDamageCauseEntityAttack 2 ActorDamageCauseProjectile 3 ActorDamageCauseSuffocation 4 ActorDamageCauseFall 5 ActorDamageCauseFire 6 ActorDamageCauseFireTick 7 ActorDamageCauseLava 8 ActorDamageCauseDrowning 9 ActorDamageCauseBlockExplosion 10 ActorDamageCauseEntityExplosion 11 ActorDamageCauseVoid 12 ActorDamageCauseSelfDestruct 13 ActorDamageCauseMagic 14 ActorDamageCauseWither 15 ActorDamageCauseStarve 16 ActorDamageCauseAnvil 17 ActorDamageCauseThorns 18 ActorDamageCauseFallingBlock 19 ActorDamageCausePiston 20 ActorDamageCauseFlyIntoWall 21 ActorDamageCauseMagma 22 ActorDamageCauseFireworks 23 ActorDamageCauseLightning 24 ActorDamageCauseCharging 25 ActorDamageCauseTemperature 26 ActorDamageCauseFreezing 27 ActorDamageCauseStalactite 28 ActorDamageCauseStalagmite 29 ActorDamageCauseRamAttack 30 ActorDamageCauseSonicBoom 31 ActorDamageCauseCampfire 32 ActorDamageCauseSoulCampfire 33 ActorDamageCauseMaceSmash 34 ActorDamageCauseAll 35 js 对于一个玩家对象plplhurt20 使用枚举plhurt20 ActorDamageCauseEntityAttackluaplhurt20治疗玩家plhealhealth治疗的心数设置玩家的生命值plsetHealthhealth生命值数为玩家设置伤害吸收属性plsetAbsorptionvalue新的值为玩家设置攻击伤害属性plsetAttackDamagevalue新的值为玩家设置最大攻击伤害属性plsetMaxAttackDamagevalue新的值为玩家设置跟随范围plsetFollowRangevalue新的值为玩家设置击退抵抗属性plsetKnockbackResistancevalue新的值 0 or 1为玩家设置幸运属性plsetLuckvalue新的值为玩家设置移动速度属性plsetMovementSpeedvalue新的值为玩家设置水下移动速度属性plsetUnderwaterMovementSpeedvalue新的值为玩家设置岩浆上移动速度属性plsetLavaMovementSpeedvalue新的值设置玩家最大生命值plsetMaxHealthhealth生命值数设置玩家饥饿值plsetHungryhunger饥饿值数使指定玩家着火plsetFiretimeisEffect着火时长单位秒会不会有火的效果js 对于一个玩家对象plplsetFire20trueluaplsetFire20true熄灭玩家plstopFire缩放玩家plsetScalescale新的玩家体积重命名玩家plrenamenewname玩家的新名字js 对于一个玩家对象plplrenameSteveluaplrenameSteve获取玩家当前站立所在的方块plgetBlockStandingOnjs 对于一个玩家对象plvar bl plgetBlockStandingOnluabl plgetBlockStandingOn获取玩家对应的设备信息对象plgetDevice设备信息对象储存了与玩家设备有关的某些信息如设备IP地址、设备类型、网络延迟等信息。 关于设备信息对象的其他信息请参考 设备信息对象 APIDevicezhmdjs 对于一个玩家对象plvar dv plgetDeviceluadv plgetDevice获取玩家主手中的物品对象plgetHand此处获取的物品对象为引用。也就是说修改此处返回的物品对象或使用其API就相当于直接操作玩家主手中对应的物品js 对于一个玩家对象plvar it plgetHandluait plgetHand获取玩家副手的物品对象plgetOffHand此处获取的物品对象为引用。也就是说修改此处返回的物品对象或使用其API就相当于直接操作玩家副手中对应的物品js 对于一个玩家对象plvar it plgetOffHandluait plgetOffHand获取玩家物品栏的容器对象plgetInventory关于容器对象的更多使用请参考 容器对象 API文档Containerzhmdjs 对于一个玩家对象plvar ct plgetInventoryluact plgetInventory获取玩家盔甲栏的容器对象plgetArmor关于容器对象的更多使用请参考 容器对象 API文档Containerzhmdjs 对于一个玩家对象plvar ct plgetArmorluact plgetArmor获取玩家末影箱的容器对象plgetEnderChest关于容器对象的更多使用请参考 容器对象 API文档Containerzhmdjs 对于一个玩家对象plvar ct plgetEnderChestluact plgetEnderChest获取玩家的重生坐标plgetRespawnPositionjs 对于一个玩家对象plvar pos plgetRespawnPositionluapos plgetRespawnPosition修改玩家的重生坐标plsetRespawnPositionpos plsetRespawnPositionxyzdimid重生坐标或者使用x y z dimid来确定重生位置jsplsetRespawnPositionposluaplsetRespawnPositionpos给予玩家一个物品plgiveItemitem amount给予的物品对象可选参数给予物品对象的数量若提供此参数则物品对象自身的Count属性将被忽略如果玩家物品栏已满将抛出多余物品js 对于一个玩家对象plplgiveItemitemluaplgiveItemitem清除玩家背包中所有指定类型的物品plclearItemtype count要清除的物品对象类型名可选参数要清除的物品数量将玩家物品栏、主手、副手、盔甲栏中所有物品的type属性与此字符串进行比较 如果相等则清除此物品js 对于一个玩家对象plplclearItemminecraftdirtplclearItemminecraftdirt 114514luaplclearItemminecraftdirtplclearItemminecraftdirt 1919刷新玩家物品栏、盔甲栏plrefreshItems在修改玩家物品之后为了促使客户端生效需要刷新玩家所有的物品js 对于一个玩家对象plplrefreshItemsluaplrefreshItems刷新玩家加载的所有区块plrefreshChunksjs 对于一个玩家对象plplrefreshChunksluaplrefreshChunks修改玩家操作权限plsetPermLevellevel目标操作权限等级 操作权限等级 对应操作权限 0 普通成员权限 1 OP权限 4 OP 控制台权限 js 对于一个玩家对象plplsetPermLevel0luaplsetPermLevel0修改玩家游戏模式plsetGameModemode目标游戏模式0为生存模式1为创造模式2为冒险模式 6为观察者模式js 对于一个玩家对象plplsetGameMode0luaplsetGameMode0提高玩家经验等级pladdLevelcount要提高的经验等级js 对于一个玩家对象plpladdLevel1luapladdLevel1降低玩家经验等级plreduceLevelcount要降低的经验等级js 对于一个玩家对象plplreduceLevel1luaplreduceLevel1获取玩家经验等级plgetLeveljs 对于一个玩家对象plvar lv plgetLevellualv plgetLevel设置玩家经验等级plsetLevelcount要设置的经验等级js 对于一个玩家对象plplsetLevel1luaplsetLevel1重置玩家经验plresetLeveljs 对于一个玩家对象plplresetLevelluaplresetLevel获取玩家当前经验值plgetCurrentExperiencejs 对于一个玩家对象plplgetCurrentExperienceluaplgetCurrentExperience设置玩家当前经验值plsetCurrentExperiencecount要设置的经验值js 对于一个玩家对象plplsetCurrentExperience1luaplsetCurrentExperience1获取玩家总经验值plgetTotalExperiencejs 对于一个玩家对象plvar xp plgetTotalExperienceluaxp plgetTotalExperience设置玩家总经验值plsetTotalExperiencecount要设置的经验值js 对于一个玩家对象plplsetTotalExperience1luaplsetTotalExperience1提高玩家经验值pladdExperiencecount要提高的经验值js 对于一个玩家对象plpladdExperience1luapladdExperience1降低玩家经验值plreduceExperiencecount要降低的经验值js 对于一个玩家对象plplreduceExperience1luaplreduceExperience1获取玩家升级所需的经验值plgetXpNeededForNextLevel注意此方法在计算时会忽略当前经验值js 对于一个玩家对象plvar ndxp plgetXpNeededForNextLevelluandxp plgetXpNeededForNextLevel传送玩家至指定服务器pltransServerserverport目标服务器IP 域名目标服务器端口js 对于一个玩家对象plpltransServer123456789 23333luapltransServer123456789 23333使玩家客户端崩溃plcrashjs 对于一个玩家对象plplcrashluaplcrash设置玩家自定义侧边栏plsetSidebartitledatasortOrder侧边栏标题侧边栏对象内容对象 对象中的每个键 值对将被设置为侧边栏内容的一行可选参数侧边栏内容的排序顺序。0为按分数升序1为按分数降序。默认值为1js 对于一个玩家对象plplsetSidebartitle aaaa 3bbb 12cc 7luaplsetSidebartitle aaaa 3bbb 12cc 7移除玩家自定义侧边栏plremoveSidebarjs 对于一个玩家对象plplremoveSidebarluaplremoveSidebar设置玩家看到的自定义Boss血条plsetBossBaruidtitlepercentcolour唯一标识符不可冲突重复一个uid对于一行bar自定义血条标题血条中的血量百分比有效范围为0100。0为空血条100为满血条颜色默认值为2REDjs 对于一个玩家对象plplsetBossBar1145141919 Hello 80 0luaplsetBossBar1145141919 Hello 80 0移除玩家的自定义的指定Boss血条plremoveBossBaruid标识符与setBossBar对应js 对于一个玩家对象plplremoveBossBar1145141919luaplremoveBossBar1145141919获取在线玩家对应的NBT对象plgetNbt写入在线玩家对应的NBT对象plsetNbtnbtNBT对象关于NBT对象的更多使用请参考 NBT接口文档NbtAPINBTzhmd获取玩家对应的NBT对象mcgetPlayerNbtuuid玩家的UUID此API的好处是可以获取到离线玩家NBT无需玩家在线无需玩家对象。写入玩家对应的NBT对象mcsetPlayerNbtuuidnbt玩家的UUIDNBT对象此API的好处是可以操作离线玩家NBT无需玩家在线无需玩家对象。覆盖玩家对应的NBT对象的特定NbtTagmcsetPlayerNbtTagsuuidnbttags玩家的UUIDNBT对象需要覆盖的NbtTag String此API的好处是可以操作离线玩家NBT无需玩家在线无需玩家对象。从存档中删除玩家对应的NBT对象的全部内容mcdeletePlayerNbtuuid玩家的UUID此API的好处是可以操作离线玩家NBT无需玩家在线无需玩家对象。为玩家增加一个TagpladdTagtag要增加的tag字符串为玩家移除一个TagplremoveTagtag要移除的tag字符串检查玩家是否拥有某个TagplhasTagtag要检查的tag字符串获取玩家拥有的所有Tag列表plgetAllTags获取玩家的Abilities能力列表来自玩家NBTplgetAbilities键 值对列表中的每一项形如mayfly 1 等等获取玩家的Attributes属性列表来自玩家NBTplgetAttributes数组中的每一项为一个键 值对列表对象ObjectAttributes对象默认含有Base Current DefaultMax DefaultMin MaxMin Name 等几种内容 。其内容形如jsonBase 0Current 0DefaultMax 1024DefaultMin 1024Max 1024Min 1024Name minecraftluck获取玩家疾跑状态plisSprinting设置玩家疾跑状态plsetSprintingsprinting是否为疾跑状态获取视线方向实体plgetEntityFromViewVectormaxDistance查找最大距离获取视线方向方块plgetBlockFromViewVectorincludeLiquidsolidOnlymaxDistancefullOnly是否包含液态方块是否仅允许 Solid 类型的方块查找最大距离是否仅允许完整方块向玩家发送数据包plsendPacketpacket数据包获取玩家所在群系IDplgetBiomeId获取玩家所在群系名称plgetBiomeName设置玩家Ability属性plsetAbilityAbilityIDvalueAbility的ID是否开启获取玩家全部药水效果plgetAllEffects为玩家添加一个药水效果pladdEffectid tick level showParticles药水效果的id见下表持续时间等级是否显示粒子为玩家移除一个药水效果plremoveEffectid药水效果的id见下表 效果 名称 数字 id 迅捷 speed 1 缓慢 slowness 2 急迫 haste 3 挖掘疲劳 miningfatigue 4 力量 strength 5 瞬间治疗 instanthealth 6 瞬间伤害 instantdamage 7 跳跃提升 jumpboost 8 反胃 nausea 9 生命恢复 regeneration 10 抗性提升 resistance 11 抗火 fireresistance 12 水下呼吸 waterbreathing 13 隐身 invisibility 14 失明 blindness 15 夜视 nightvision 16 饥饿 hunger 17 虚弱 weakness 18 中毒 poison 19 凋零 wither 20 生命提升 healthboost 21 伤害吸收 absorption 22 饱和 saturation 23 飘浮 levitation 24 中毒致命 fatalpoison 25 潮涌能量 conduitpower 26 缓降 slowfalling 27 不祥之兆 badomen 28 村庄英雄 villagehero 29 黑暗 darkness 30 将玩家对象转换实体对象entoEntity判断是否为模拟玩家plisSimulatedPlayer模拟玩家由于与玩家API重合过多未生成新的模拟玩家类创建一个模拟玩家mcspawnSimulatedPlayernamepos mcspawnSimulatedPlayernamexyzdimid模拟玩家名称生成生物的位置的坐标对象或者使用x y z dimid来确定生成位置模拟玩家 函数每一个模拟玩家对象都包含一些可以执行的成员函数成员方法。对于某个特定的模拟玩家对象sp可以通过以下这些函数对这个模拟玩家进行一些操作模拟重生spsimulateRespawn参考mojanggametest docshttpslearnmicrosoftcomzhcnminecraftcreatorscriptapiminecraftservergametestsimulatedplayerviewminecraftbedrockexperimentalrespawn模拟攻击spsimulateAttacktarget可选参数攻击目标默认为视线方向上的实体参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerattack模拟破坏spsimulateDestroyposfacespsimulateDestroyblockface可选参数要破坏的方块的坐标默认为视线方向上的方块可选参数要破坏的方块默认为视线方向上的方块可选参数从哪面破坏参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerbreakblock模拟断开连接spsimulateDisconnect模拟交互spsimulateInteracttargetspsimulateInteractposfacespsimulateInteractblockface可选参数模拟交互目标默认为视线方向上的方块或实体可选参数模拟交互目标默认为视线方向上的方块或实体可选参数模拟交互目标默认为视线方向上的方块或实体可选参数模拟交互目标方块的面参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerinteract模拟跳跃spsimulateJump参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerjump模拟看向某方块或实体spsimulateLookAtpos lookDurationspsimulateLookAtentity lookDurationspsimulateLookAtblock lookDurration warninglookDurration仅在0813以及之后的版本中可用要看向的实体要看向的坐标要看向的方块模拟玩家看向目标的持续时间 0 立刻 1 持续 2 不变直到移动参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerlookatblock模拟设置身体角度spsimulateSetBodyRotationrot要设置的角度参考mojanggametest docshttpslearnmicrosoftcomzhcnminecraftcreatorscriptapiminecraftservergametestsimulatedplayerviewminecraftbedrockexperimentalrotatebody相对玩家坐标系移动spsimulateLocalMove移动方向可选参数移动速度默认为1相对世界坐标系移动spsimulateWorldMove移动方向可选参数移动速度默认为1直线移动到坐标spsimulateMoveTo目标位置可选参数移动速度默认为1参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayermovetolocation 注如需自动寻路请考虑使用 模拟导航移动模拟导航移动spsimulateNavigateToentityspeedspsimulateNavigateToposspeed导航目标导航目标可选参数移动速度默认为1参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayernavigatetoblock 返回值示例jsonisFullPath falsepath 000000000此数据的目标坐标为020路径终点为100所以isFullPath为false但由于路径不为空所以模拟玩家将会移动至100坐标模拟导航移动多目标spsimulateNavigateToposArrayspeed导航目标可选参数移动速度默认为1参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayernavigatetolocations模拟使用物品spsimulateUseItemslotposfacerelativespsimulateUseItemitemposfacerelative可选参数要使用的物品默认为选中物品可选参数要使用的物品所在的槽默认为选中物品可选参数目标坐标默认为朝向方块坐标可选参数目标方块的面默认为0可选参数相对方块偏移坐标默认为050505参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayeruseitem模拟停止破坏方块spsimulateStopDestroyingBlock参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerstopbreakingblock模拟停止交互spsimulateStopInteracting参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerstopinteracting模拟停止移动spsimulateStopMoving参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerstopmoving模拟停止使用物品spsimulateStopUsingItem参考mojanggametest docshttpsdocsmicrosoftcomzhcnminecraftcreatorscriptapimojanggametestsimulatedplayerstopusingitem 计分板 API在脚本引擎中使用「计分项对象」来操作和获取某一个特定的计分项变量并且提供了很多其他操作计分板的通用接口MC使用 计分项 作为计分板系统的核心每一个计分项拥有一个名字并可以用来跟踪特定的玩家、实体甚至字符串目标。计分项中记录着每一个跟踪目标各自对应的分数。获取一个计分项对象通过下面的接口来获取一个计分项对象并进行相关操作创建一个新的计分项mcnewScoreObjectivenamedisplayName计分项名称 计分项显示名称 此接口的作用类似命令 scoreboard objectives add name displayName dummy获取某个已存在的计分项mcgetScoreObjectivename要获取的计分项名称获取所有计分项mcgetAllScoreObjectives此接口的作用类似命令 scoreboard objectives list获取某个处于显示状态的计分项mcgetDisplayObjectiveslot待查询的显示槽位名称可以为sidebarbelownamelist计分项对象 属性每一个计分项对象都包含一些固定的对象属性。对于某个特定的计分项对象ob有以下这些属性 属性 含义 类型 obname 计分项名称 String obdisplayName 计分项的显示名称 String 这些对象属性都是只读的无法被修改计分项对象 函数每一个计分项对象都包含一些可以执行的成员函数成员方法。对于某个特定的计分项对象ob可以通过以下这些函数对这个计分项进行一些操作获取跟踪的某个目标的分数obgetScoretarget待查询的跟踪目标可传入玩家对象或者任意字符串修改某个目标的分数设置分数 obsetScoretargetscore 增加分数 obaddScoretargetscore 减少分数 obreduceScoretargetscore计分项跟踪的目标可传入玩家对象或者任意字符串要设置增加减少的分数 warning若计分项不存在则会尝试创建计分项此时会返回0当target为String时或null当target为Player时 原因参见 971httpsgithubcomLiteLDevLeviLaminaissues971issuecomment1385047649停止跟踪某个目标obdeleteScoretarget计分项跟踪的目标可传入玩家对象或者任意字符串停止跟踪将直接删除这个目标对应的计分项数值下次如需要访问需要再次创建设置计分项的显示状态obsetDisplayslotsortOrder0显示槽位名称字符串可以为sidebarbelownamelist可选参数排序方式可以为0升序或1降序默认值为0其他计分板 API下面这些API提供了更多操作计分板系统的API获取在线玩家计分项的分数方便函数plgetScorename计分项名称 使用前必须保证对应的计分项已经存在JavaScriptjs对于一个玩家对象pllogYou have moneyplgetScoremoney获取玩家计分项的分数可查询离线玩家计分板mcgetPlayerScoreuuid name玩家的UUID 计分项名称 修改在线玩家计分项的分数方便函数设置分数 plsetScorenamevalue 增加分数 pladdScorenamevalue 减少分数 plreduceScorenamevalue计分项名称 要设置 增加 减少的数值 若计分项不存在则会返回false并创建计分项JavaScriptjs对于一个玩家对象plplsetScoremoney10000pladdScoremoney100plreduceScoremoney50修改玩家计分项的分数可修改离线玩家计分板设置分数 mcsetPlayerScoreuuid name value 增加分数 mcaddPlayerScoreuuid name value 减少分数 mcreducePlayerScoreuuid name value 移除分数 mcdeletePlayerScoreuuid name玩家的UUID 计分项名称 要设置 增加 减少的数值 玩家停止跟踪计分项方便函数pldeleteScorename计分项名称 使用前必须保证对应的计分项已经存在JavaScriptjs对于一个玩家对象plpldeleteScorewhat移除一个已存在的计分项mcremoveScoreObjectivename计分项名称 此接口的作用类似命令 scoreboard objectives remove name使计分项停止显示mcclearDisplayObjectiveslot显示槽位名称字符串可以为sidebarbelownamelist 服务端设置 API下面这些API提供了自定义某些服务器设置的接口获取服务器版本号mcgetBDSVersion获取服务器协议版本mcgetServerProtocolVersion设置服务器MOTD字符串 mcsetMotdmotd目标MOTD字符串 设置服务器最大玩家数 mcsetMaxPlayersnum最大玩家数 获取服务器游戏时间 mcgetTimeTimeID想要查询的时间 0 代表daytime1 代表gametime2 代表day其中daytime 代表自当天日出后流逝的游戏刻数gametime 代表世界总共流逝的游戏刻数day 代表已流逝的游戏天数。设置服务器游戏时间 mcsetTimetick想要设置的时间获取服务器天气 mcgetWeather设置服务器天气 mcsetWeatherWeatherID想要设置的天气 0 代表晴天1 代表雨天2 代表雷暴脚本引擎 GUI表单界面文档 这里API使你可以在游戏中创建、修改或者影响 GUI界面很明显清晰直观的UI界面有助于玩家快速上手插件的使用提供良好的用户体验。 表单相关 API对于某个特定的玩家对象pl有以下这些表单接口可用向玩家发送模式表单模式表单包含一个标题、一个文本显示框以及两个按钮plsendModalFormtitlecontentconfirmButtoncancelButtoncallbackforUpdating表单标题表单内容按钮1文本的字符串按钮2文本的字符串玩家点击按钮之后被调用的回调函数。可选参数在0110中加入是否为表单更新默认值为false即非表单更新参数callback的回调函数原型functionplayerresultreason与表单互动的玩家对象玩家点击确定按钮为true取消按钮为false 如果id为Null则代表玩家取消了表单表单被取消的原因0 UserClosed 1 UserBusyreason可能会是null向玩家发送普通表单普通表单包含一个标题、一个文本显示框以及若干按钮可以设置按钮上显示的图标 由于按钮的内容设置相对复杂建议使用下一节的表单构建器API更好地完成这项任务。plsendSimpleFormtitlecontentbuttonsimagescallbackforUpdating表单标题表单内容各个按钮文本的字符串数组各个按钮对应的图片路径玩家点击按钮之后被调用的回调函数。可选参数在0110中加入是否为表单更新默认值为false即非表单更新参数callback的回调函数原型functionplayeridreason与表单互动的玩家对象玩家点击的表单按钮的序号从0开始编号 如果id为Null则代表玩家取消了表单表单被取消的原因0 UserClosed 1 UserBusyreason可能会是null图片路径参数 images 使用材质包路径或者URL来标识按钮对应的图标。 对于表单上的每个按钮如下设置对应的图标1 如果使用材质包路径图片路径应该形如 texturesitemsapple2 如果使用URL路径那么在这里放入完整的URL即可形如 httpswwwbaiducomimgflexiblelogopcresultpng3 如果这个按钮你不需要显示图片那将对应的图片路径设置为空字符串即可向玩家发送自定义表单JSON格式自定义表单可以包含丰富的自定义控件。 由于相关JSON定义格式相对复杂建议使用下一节的表单构建器API更好地完成这项任务。plsendCustomFormjsoncallbackforUpdating自定义表单json字符串玩家提交表单之后被调用的回调函数。可选参数在0110中加入是否为表单更新默认值为false即非表单更新参数callback的回调函数原型functionplayerdatareason与表单互动的玩家对象返回的表单内容数组 数组中第一项一定为Null从第二项开始按表单上的控件顺序储存了每一个控件的内容 如果data只为Null则代表玩家取消了表单表单被取消的原因0 UserClosed 1 UserBusyreason可能会是null关闭玩家正在打开的表单plcloseForm 普通表单构建器 API 这些API可以协助开发者方便地构造一个普通表单脚本引擎提供了普通表单对象来方便地创建一个自定义表单并发送至指定玩家。创建表单对象在使用这些API之前你需要先用这个函数创建一个空白的普通表单对象mcnewSimpleForm添加表单元素创建完之后你就可以用下面这些成员函数成员方法向对象中增加新的表单元素。 对于某个特定的表单对象fm有以下这些函数可以使用设置表单的标题fmsetTitletitle表单的标题设置表单的内容fmsetContentcontent表单的文本内容向表单内增加一行按钮fmaddButtontextimage按钮文本的字符串可选参数按钮图片所在路径图片路径参数 image 使用材质包路径或者URL来标识按钮对应的图标。 对于表单上的每个按钮如下设置对应的图标1 如果使用材质包路径图片路径应该形如 texturesitemsapple2 如果使用URL路径那么在这里放入完整的URL即可形如 httpswwwbaiducomimgflexiblelogopcresultpng3 如果这个按钮你不需要显示图片那不传入此参数即可向表单内增加标头fmaddHeadertext标头内容向表单内增加一行文本fmaddLabeltext一行文本向表单内增加分隔线fmaddDivider发送表单最后在一切就绪之后你可以将配置好的表单对象发送给玩家并监听玩家的互动消息 表单对象可以被反复发送每次发送都会返回一个不同的表单ID并在有玩家互动时调用各自设置的回调函数不会打架。对于某个玩家对象pl使用函数plsendFormfmcallbackforUpdating配置好的表单对象玩家与表单元素互动之后被调用的回调函数。可选参数在0110中加入是否为表单更新默认值为false即非表单更新参数callback的回调函数原型functionplayeridreason与表单互动的玩家对象玩家点击的表单按钮的序号从0开始编号 如果id为Null则代表玩家取消了表单表单被取消的原因0 UserClosed 1 UserBusyreason可能会是null 自定义表单构建器 API 这些API可以协助开发者方便地构造一个自定义表单不再需要为编写JSON麻烦而头疼脚本引擎提供了自定义表单对象来方便地创建一个自定义表单并发送至指定玩家。创建表单对象在使用这些API之前你需要先用这个函数创建一个空白的自定义表单对象mcnewCustomForm添加表单元素创建完之后你就可以用下面这些成员函数成员方法向对象中增加新的表单元素。 对于某个特定的表单对象fm有以下这些函数可以使用设置表单的标题fmsetTitletitle表单的标题向表单内增加标头fmaddHeadertext标头内容向表单内增加一行文本fmaddLabeltext一行文本向表单内增加分隔线fmaddDivider向表单内增加一行输入框fmaddInputtitleplaceholderdefaulttooltip输入框描述文本可选参数输入框内的提示字符可选参数输入框中默认存在的内容可选参数在0120中加入提示文本向表单内增加一行开关选项fmaddSwitchtitledefaulttooltip开关选项描述文本可选参数开关的默认状态 开 关可选参数在0120中加入提示文本向表单内增加一行下拉菜单fmaddDropdowntitleitemsdefaulttooltip下拉菜单描述文本下拉菜单中的选项文本列表可选参数下拉菜单默认选中的列表项序号。 序号从0开始编号。默认为0即默认选中列表的第一项可选参数在0120中加入提示文本向表单内增加一行游标滑块fmaddSlidertitleminmaxstepdefaulttooltip游标滑块描述文本游标滑块最小值游标滑块最大值可选参数游标滑块调整的最小分度值默认为1可选参数游标滑块默认初始格数数值必须在最小和最大格数之间。 默认为0即滑块位于滑块行的开头可选参数在0120中加入提示文本向表单内增加一行步进滑块fmaddStepSlidertitleitemsdefaulttooltip步进滑块描述文本步进滑块的选项文本列表可选参数步进滑块默认初始选项。序号从0开始编号 默认为0即滑块位于滑块行的开头可选参数在0120中加入提示文本设置提交按钮的文本 warning此API仅在0110及更高版本中可用。fmsetSubmitButtontext提交按钮的文本发送表单最后在一切就绪之后你可以将配置好的表单对象发送给玩家并监听玩家的互动消息 表单对象可以被反复发送每次发送都会返回一个不同的表单ID并在有玩家互动时调用各自设置的回调函数不会打架。对于某个玩家对象pl使用函数plsendFormfmcallbackforUpdating配置好的自定义表单对象玩家提交表单之后被调用的回调函数。可选参数在0110中加入是否为表单更新默认值为false即非表单更新参数callback的回调函数原型functionplayerdatareason与表单互动的玩家对象返回的表单内容数组 数组中中按表单上的控件顺序储存了每一个控件的内容 如果data为Null则代表玩家取消了表单表单被取消的原因0 UserClosed 1 UserBusyreason可能会是null 脚本引擎 特定脚本语言开发须知 开发语言支持情况通过 ScriptXhttpsgithubcomTencentScriptX 项目的支持脚本引擎使用同一套源代码对多种开发语言进行了适配。 同时由于API保持一致使各种语言得以共享一份开发文档大大降低了维护难度。目前脚本引擎支持使用如下语言编写插件 语言后端 备注 JavaScript 使用 QuickJS 引擎运行插件支持 ES Module 机制 Lua 使用 CLua 引擎运行插件 Nodejs 改造 Nodejs 使其适合嵌入工作支持 npm 包管理 Python 使用 CPython 引擎运行插件支持 pip 包管理 tip如果需要使用 C、Go、Rust 等原生语言编写插件请移步 主页httpslaminalevimcorg 查看其他语言文档JavaScript 语言支持说明Lua 语言支持说明等常用库Nodejs 支持说明 Nodejs 插件开发方法1 首先安装NodeJs2 创建一个新的目录进行插件开发。在此目录启动终端执行npm init命令。根据 npm 的提示创建新项目填写项目的相关信息。3 在填写的入口点文件中编写插件代码4 如果有需要可以创建多个源码文件并且通过 require 来引入他们。合理的对源码进行分文件拆分编写有助于提高项目结构的清晰度方便后续对插件进行进一步的维护和扩展。 Nodejs 插件打包 部署方法安装依赖包整个过程无需人工干预Python 语言支持说明import支持现代项目管理机制Python 单文件插件开发方法 Python 多文件插件开发方法PDM 包管理器pdmprojectpdmhttpsgithubcompdmprojectpdm自动生成以便于进行插件项目的创建和维护。下面是具体的插件开发流程1 首先安装Python 31282 在终端中执行pip install user pdm命令安装 pdm 包管理工具3 创建一个新的目录进行插件开发。在此目录启动终端执行pdm init命令。根据pdm工具的提示创建新项目填写项目的相关信息。requirementstxt中描述的依赖都将被处理并自动安装。4 接下来创建initpy文件并在其中编写插件代码。加载插件时Python解释器会首先读取并执行这个文件。5 如果有需要可以创建多个源码文件并且通过 import 来引入他们。合理的对源码进行分文件拆分编写有助于提高项目结构的清晰度方便后续对插件进行进一步的维护和扩展。 Python 多文件插件打包 部署方法安装依赖包整个过程无需人工干预Python插件开发的已知问题平心而论CPython的代码质量和维护状况有些堪忧。下面给出了一些开发Python插件时需要注意的地方其中有不少都是由CPython本身的Bug引起的1 暂时不要使用threading asyncio等特性api内部并没有考虑到子解释器的存在因此一旦使用会发生死锁、崩溃等问题。2 所有Python引擎的sysstdin被禁用脚本引擎 NBT 文档 NBT二进制命名标签Named Binary Tags 格式为Minecraft中用于向文件中存储数据的一种存储格式。 NBT格式以树形结构并配以许多标签 的形式存储数据。所有的标签都有一个独立的ID和名称。 Minecraft Wiki这里为脚本提供了操作 NBT 数据类型的能力。 NBT 接口的支持极大的提高了游戏的可扩展性游戏中使用被称为 NBT标签 的节点来标识一项NBT数据。NBT标签中可以储存普通数据、List、Compound 等多种数据类型。 在LegacyScriptEngine中每种NBT数据类型都有其对应的数据类型我们统称他们为「NBT对象」。 脚本引擎类型与NBT数据类型的对照如下 NBT数据类型 对应的NBT对象类型 类型说明来自MC Wiki Byte NbtByte 有符号字节 或 布尔值8位 Short NbtShort 有符号短整型16位 Int NbtInt 有符号整形32位 Long NbtLong 有符号长整型64位 Float NbtFloat 单精度浮点数 Double NbtDouble 双精度浮点数 ByteArray NbtByteBuffer 字节数组 String NbtString UTF8 字符串 List NbtList NBT 列表类似于 数组 Compound NbtCompound NBT 标签类似于 键值对列表 每种数据类型可能有略微不同的使用接口。下面对他们作分别介绍 NBT 对象通用接口每一个 NBT 对象都包含一些可以执行的成员函数成员方法 对于任何种类的NBT对象都有下面这些通用的接口。以名为nbt的某个NBT对象为例获取NBT对象储存的数据类型nbtgetType可能的返回值有NBTEnd NBTByte NBTShort NBTInt NBTLong NBTFloat NBTDouble NBTByteArray NBTString NBTList NBTCompound将NBT对象转换为JSON字符串nbttoStringspace可选参数如果要格式化输出的字符串则传入此参数 代表每个缩进的空格数量这样生成的字符串更适合人阅读 此参数默认为1即不对输出字符串进行格式化提示如果这个NBT对象储存的是List或者Compound类型将递归展开为Array或Object 如果这个NBT对象储存的是ByteArray类型输出的字节串将先进行base64编码后再输出 上述函数输出的字符串符合JSON标准格式但是无法进行反序列化。 如果有反序列化的需求请使用 NBT标签类 提供的的 SNBT 接口 NbtCompound 标签类型一个 NbtCompound 代表一个完整的标签里面储存了一系列键值对类似于对象 表这样的数据结构。 通过 NbtCompound 对象的接口才可以进行 NBT 标签所独有的一些操作。获取一个 NBT 标签对象从现有的 NBT 对象中解析获取详见 NbtList 列表类型NBTListzhmd 和 NbtCompound 标签类型NBTCompoundzhmd 文档创建新的 NBT 标签对象JavaScript new NbtCompounddata Lua NbtCompounddata传入一个 NBT 对象构成的对象。对象中允许包含其他数组 对象结构但内容必须都为 NBT 对象JavaScriptjsvar nbt new NbtCompoundname1 new NbtInt3name2 new NbtStringtestname3 new NbtListnew NbtFloat40new NbtFloat60name4 new NbtLong66666Lualualocal nbt NbtCompoundname1 NbtInt3name2 NbtStringtestname3 NbtListNbtFloat40NbtFloat60name4 NbtLong66666从 SNBT 字符串生成 NBT 标签对象NBTparseSNBTsnbt 你要解析的 SNBT 字符串 SNBT 字符串中必须包含一个完整的 Compound从二进制 NBT 数据生成 NBT 标签对象NBTparseBinaryNBTnbt 你要解析的二进制 NBT 数据 二进制 NBT 数据中必须包含一个完整的 Compound对于某个一个 NbtCompound 类型的对象 comp有如下这些接口获取所有的键compgetKeys获取键对应的值的数据类型compgetTypeOfkey要查询的键名可能的返回值有NBTEnd NBTByte NBTShort NBTInt NBTLong NBTFloat NBTDouble NBTByteArray NBTString NBTList NBTCompound设置键对应的 NBT 对象compsetTagkeytag要操作的键名要写入的 NBT 对象它承载着具体的NBT数据 写入数据类型必须和键对应的值储存的数据类型一致键名可以不存在读取键对应的 NBT 对象compgetTagkey要操作的键名删除键对应的 NBT 对象compremoveTagkey要操作的键名。键名必须已经存在一些协助 NBT 对象操作的方便函数很明显在修改 NBT 的某些值的时候纯粹使用 NBT 对象会显得麻烦而语法复杂。 因此这里还提供了一些简化对象操作的方便函数通过直接操作指定位置的数据而避免通过 NBT 对象中转可以一定程度上降低代码量设置键对应的值的具体数据compsetEndkey compsetBytekeydata compsetShortkeydata compsetIntkeydata compsetLongkeydata compsetFloatkeydata compsetDoublekeydata compsetByteArraykeydata compsetStringkeydata 要操作的键名要写入的具体数据 写入数据类型必须和键对应的值储存的数据类型一致键名可以不存在读取键对应的值的具体数据compgetDatakey 要操作的键名将 NBT 标签对象转换为 ObjectcomptoObject将 Compound 的内容转换为脚本引擎对象把数据项都转换为脚本引擎数据类型储存于对象的对应 key 中方便读取和处理 如果 Compound 某一项储存的是 List 或者 Compound 类型的 NBT将在对应位置递归展开为 Array 或 Object将 NBT 标签对象序列化为 SNBTnbttoSNBTspace可选参数如果要格式化输出的字符串则传入此参数 代表每个缩进的空格数量这样生成的字符串更适合人阅读 此参数默认为 1即不对输出字符串进行格式化 除了普通的二进制 NBT 之外另一种玩家更熟悉的 NBT 是纯文本形式的通常在命令httpszhminecraftwikiw命令里使用。这种格式常被称为SNBT字符串化的二进制命名标签Stringified NBT Minecraft Wiki将 NBT 标签对象 序列化为二进制 NBTcomptoBinaryNBT 只有完整的顶层Compound标签可以被转换为二进制 NBT销毁此 NBT 标签对象compdestroy注意只有根 Compound 标签可以被销毁而且请谨慎使用此函数不当的使用将会造成服务器崩溃 合适的销毁有助于解决内存占用问题。在销毁完后请千万不要再使用此 NBT 对象和他的所有子对象 NbtList 列表类型一个NbtList代表一个列表里面储存了一列 NBT 对象类似于列表 数组这样的数据结构。 通过NbtList对象的接口才可以进行 NBT 列表所独有的一些操作。 获取一个 NBT 列表对象从现有的NBT对象中解析获取详见 NbtList 列表类型NBTListzhmd 和 NbtCompound 标签类型NBTCompoundzhmd 文档创建新的NBT列表对象JavaScript new NbtListdata Lua NbtListdata传入一个NBT对象构成的数组。数组中允许包含其他数组 对象结构但内容必须都为NBT对象对于某个一个NbtList类型的对象list有如下这些接口获取列表长度listgetSize获取某个下标位置储存的数据类型listgetTypeOfindex要查询的目标下标可能的返回值有NBTEnd NBTByte NBTShort NBTInt NBTLong NBTFloat NBTDouble NBTByteArray NBTString NBTList NBTCompound设置某个下标位置的NBT对象listsetTagindextag要操作的目标下标要写入的 NBT 对象 写入对象的数据类型必须和下标位置储存的数据类型一致且下标不能超出有效下标的最大值读取某个下标位置的NBT对象listgetTagindex要操作的目标下标往列表末尾追加一个NBT对象listaddTagtag要追加的 NBT 对象删除某个下标位置的NBT对象listremoveTagindex要删除的目标下标 下标不能超出有效下标的最大值一些协助 NBT 对象操作的方便函数很明显在修改NBT的某些值的时候纯粹使用NBT对象会显得麻烦而语法复杂。 因此这里还提供了一些简化对象操作的方便函数通过直接操作指定位置的数据而避免通过NBT对象中转可以一定程度上降低代码量设置某个下标位置的具体数据listsetEndindex listsetByteindexdata listsetShortindexdata listsetIntindexdata listsetLongindexdata listsetFloatindexdata listsetDoubleindexdata listsetByteBufferindexdata listsetStringindexdata 要操作的目标下标要写入的具体数据 写入数据类型必须和下标位置储存的数据类型一致且下标不能超出有效下标的最大值读取某个下标位置的具体数据listgetDataindex 要操作的目标下标将List类型转换为ArraylisttoArray将List的内容转换为脚本引擎数组 列表把数据项都转换为脚本引擎数据类型储存于数组 列表的对应下标中方便读取和处理 如果List某一项储存的是List或者Compound类型的 NBT将在对应位置递归展开为Array或Object NBT 普通数据类型我们把除了 NbtList 和 NbtCompound 类型以外的其他NBT对象统称为 普通数据 类型。这些对象只储存了简单的数据内部不含有其他复杂结构。获取一个 NBT 普通数据对象从现有的NBT对象中解析获取详见 NbtList 列表类型NBTListzhmd 和 NbtCompound 标签类型NBTCompoundzhmd 文档创建新的NBT数据对象JavaScript new NbtBytedata new NbtShortdata new NbtIntdata new NbtLongdata new NbtFloatdata new NbtDoubledata new NbtByteArraydata new NbtStringdata Lua NbtBytedata NbtShortdata NbtIntdata NbtLongdata NbtFloatdata NbtDoubledata NbtByteArraydata NbtStringdata 根据你要创建的对象类型设置初始数据传入的数据类型需要能够初始化对应类型的数据 可以不传入此参数对于一个储存普通数据类型的NBT对象 value有如下成员函数设置对象的数据valuesetdata根据这个NBT对象的数据类型写入对应类型的数据 如对于一个Float类型的 NBT 对象你需要传入一个Float类型的值读取对象的数据valueget脚本引擎 插件开发概述 放在前面LegacyScriptEngine以下简称LSE脚本引擎是一个基岩版官方服务端 Bedrock Dedicated Server以下简称BDS的插件框架提供强大的跨语言脚本插件支持能力和稳定的开发API支持。 欢迎参与到脚本引擎的插件开发中来从这里开始你将逐步熟悉脚本插件开发的基本要素和流程。在接触开发之前你需要对脚本引擎有一个成体系的认识。这里的文档首先将帮助你建立一个大概的知识框架。 首先熟悉他们这将是你学习开发的过程中非常重要的一环。 数据类型众所周知类型系统通常都是一个设计框架中比较关键的部分。 因此首先你需要熟悉几种在使用 API 文档的过程中会频繁用到的数据类型。 这些数据类型的名词会频繁出现在开发文档当中请务必首先对他们足够熟悉。通用数据类型约定虽然脚本语言通常是弱类型的不需要关注具体的数据类型但由于脚本引擎支持多种不同的脚本语言为了方便对接API下面定义一些通用的数据类型以及到对应脚本语言类型的映射关系。 引擎数据类型 JavaScript 数据类型 Lua 数据类型 数据类型说明 Null nullundefined 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 字节数组 除了上述了标准类型之外还存在一些引擎自定义的对象类型。 API文档描述约定众所周知一个好的帮助文档自然离不开统一简洁的格式和一目了然的外观。 因此为了文档的格式统一和规范接下来需要统一规定一下脚本引擎的帮助文档描述约定。 对于接下来你看到的所有API文档都有这样的写作规则1 关于文档中对 函数参数类型 的描述 函数参数将按照 参数名 参数类型 格式描述 例如 cmd String 表示一个字符串类型的变量cmd 如果参数类型出现Array表示一个以内的变量为内容的数组 列表 2 关于文档中对 可选参数 的描述 如果在参数描述处出现 可选参数 则代表你可以不传入这个参数。 当你不传入这个参数的时候引擎将使用描述中给出的默认值。 在API接口参数中可选参数会被 框起来。 形如pltellmsgtype这里的type就属于可选参数在熟悉上面这些基础设施之后你可以开始逐步阅读其他各特定内容的文档了。 如果碰到遗忘了的东西可以多翻回来看看。 插件开发小贴士这里有一些在开发插件的时候的建议希望可以帮到你在条件允许的情况下尽量使用他人已经编写好的特定功能的库而不是每个功能都自己编写一遍。这样有利于生态的整合和发展。在设计界面和配置的时候最好考虑到用户的感受。UI和命令等对外交互的内容尽量做到清晰和一目了然符合常规的使用习惯。鼓励大家向其他平台已有的优秀插件学习也欢迎大家作出自己的创新。 调试插件你可以输入这些命令来进入相应的调试模式在调试模式下你输入的所有文本将被解析为脚本并实时执行就像浏览器的开发工具的控制台那样。如果发生任何错误你会看到一个错误报告。你可以输入jsdebugluadebug并回车以退出调试模式。 插件加载相关 API这里提供了一些与加载器操作相关的接口。Properties 属性 类型 描述 lllanguage String LeviLamina使用的语言。例如zhHans、en和ruRU llmajor Integer 主版本号如 210 里的 2 llminor Integer 次版本号如 210 里的 1 llrevision Integer 修订版本号如 210 里的 0 llstatus Integer 版本状态 0为Dev 1为Beta 2为Release llscriptEngineVersion String 脚本引擎的版本 llisWine Boolean 是否处于Wine环境下 llisDebugMode Boolean 是否处于debug模式 llisBeta Boolean 当前版本是否为测试版 llisDev Boolean 当前版本是否为开发版 llisRelease Boolean 当前版本是否为发布版本 llpluginsRoot String LeviLamina插件的根目录 获取 LegacyScriptEngine 版本字符串 warning在096之前的版本中该函数返回的是LeviLamina的版本。llversionString获取有关插件的信息llgetPluginInfoname插件名称 属性 描述 类型 pluginname 插件名称 String plugindesc 插件描述 String plugintype 插件类型 String pluginversion 插件版本数组形式 ArrayIntegerIntegerInteger pluginversionStr 插件版本 String pluginfilePath 插件路径 String pluginothers 其他信息 Object 获取当前插件的信息llgetCurrentPluginInfo列出所有已加载的插件lllistPlugins列出所有加载的插件信息llgetAllPluginInfo设置插件卸载时调用的函数 warning该函数仅在096及更高版本中可用。llonUnloadfunc插件卸载时调用的函数远程函数调用导出函数为了可以让开发者开发的前置插件能够为其他插件提供接口和服务这里提供了远程函数调用功能让一个 原生 或 脚本插件可以调用另一个插件中已有的函数。llexportsfuncnamespacename要导出的函数函数的命名空间名只是方便用于区分不同插件导出的API函数的导出名称。其他插件根据导出名称来调用这个函数注意如果导出的函数的命名空间和名字与另一个已经导出的函数完全相同将会导出失败。选定命名空间和导出名称时请适当选择。导入函数当你已经得知有插件导出函数之后为了可以使用他导出的函数首先需要将这个函数导入到你自己的脚本系统中 脚本引擎提供了接口 import 来导入其他插件已经导出的函数。llimportsnamespacename要导入的函数使用的命名空间名称要导入的函数使用的导出名称llimports 的返回值是一个函数。当你调用这个函数时跨插件调用的流程将在后台自动完成。调用函数的参数将被包装并传递给远程函数此函数的返回值即是远程函数执行完毕之后返回的返回值。远程调用参数类型对照其中Type可以为其他受支持的类型 C层类型 脚本引擎类型 NET托管类型 内部类型备注 stdnullptrt Null null Nothing nullptr stdnullptrt bool Boolean Boolean bool int64 double Number Int64 Double RemoteCallNumberType stdstring String String stdstring stdvectorType Array ListType stdvectorType stdunorderedmapstdstringType Object DictionaryStringType stdunorderedmapstdstringType Actor Entity MCActor Actor Player Player MCPlayer Player ItemStack stduniqueptrItemStack Item RemoteCallItemType RemoteCallItemType Block BlockInstance Block RemoteCallBlockType RemoteCallBlockType BlockActor BlockActor MCBlockActor BlockActor Container Container MCContainer Container Vec3stdpairVec3int FloatPos MCVec3 RemoteCallWorldPosType RemoteCallWorldPosType BlockPosstdpairBlockPos int IntPos MCBlockPos RemoteCallBlockPosType RemoteCallBlockPosType CompoundTagstduniqueptrCompoundTag NBTCompound RemoteCallNbtType RemoteCallNbtType 远程调用函数举例说明比如有一个插件导出了某个函数函数导出使用的命名空间为 AAA导出函数名称为 Welcome 当你使用 welcome llimportsAAAwelcome 完成导入之后你就可以直接在下面执行welcomehello2true函数的参数将被自动转发到对应的目标函数执行执行完毕之后将返回回应的目标函数的返回值整个过程都是自动完成的。注意在调用函数的时候需要保证你传入的参数和目标函数接受的参数数量和类型都是正确且一一对应的。否则将会发生错误。判断远程函数是否已导出llhasExportednamespacename函数使用的命名空间名称函数使用的导出名称将字符串作为脚本代码执行llevalstr要作为脚本代码执行的字符串脚本引擎 脚本辅助接口文档 这里提供了大量的 辅助功能 包括日志功能、加载器功能接口等等。他们让你开发脚本变得更加容易而自然避免了很多无谓的细节问题的纠缠。 通用日志 API以往按某种格式输出日志到指定位置是一件非常麻烦的事情。 如今脚本引擎为你提供了方便的通用日志接口。概念关于日志输出等级为了给日志的优先程度和重要性进行分级我们引入了 日志输出等级 的概念。 日志输出等级越高日志的内容越详细但同时输出的日志量也越大 详见下表 日志输出等级 对应等级名称 实际输出日志内容 0 Slient 不输出任何日志 1 Fatal 仅输出 严重错误信息 2 Error 输出 严重错误、错误信息 3 Warn 输出 严重错误、错误、警告信息 4 Info 输出 严重错误、错误、警告、提示信息 5 Debug 输出 严重错误、错误、警告、提示 和 调试信息 通过 日志输出等级 设置你可以很方便地过滤掉某些在生产环境中没必要输出的信息。日志输出等级的默认值为4也就是说除了调试信息以外其他种类的日志都将被输出。 通过下面给出的一些 API 你可以将日志输出等级调整为你自己想要的值。设置输出配置在使用通用日志接口之前你需要先按你的需求修改一下日志输出的某些配置设置你可以通过修改设置自由选择将日志发向控制台、文件甚至某个玩家 这些设置是可以同时存在的比如说你可以设置同时发送到控制台和文件 如果你不修改任何设置默认情况 下日志仅会输出到控制台。设置日志是否输出到控制台loggersetConsoleisOpenlogLevel设置日志是否输出到控制台 开关默认是打开状态。可选参数控制台的日志输出等级默认为4设置日志是否输出到文件loggersetFilefilepathlogLevel设置日志输出到的文件路径 如果传入空字符串或者Null则代表关闭到文件的输出。 开关默认是关闭状态可选参数文件的最小日志输出等级默认为4如果要输出到文件我们提倡您将日志统一输出到BDS根目录logs文件夹下以方便整理和检查。设置日志是否输出到某个玩家loggersetPlayerplayerlogLevel设置日志输出到的目标玩家对象 如果传入Null则代表关闭到玩家的输出。 开关默认是关闭状态可选参数玩家的最小日志输出等级默认为4这是为了方便游戏内调试而设计的功能输出到玩家的日志会被当作聊天消息显示在目标玩家的屏幕上输出日志函数在设置完毕之后你就可以用这里的函数输出日志了loggerlogdata1data2 输出普通文本 loggerdebugdata1data2 输出调试信息 loggerinfodata1data2 输出提示信息 loggerwarndata1data2 输出警告信息 loggererrordata1data2 输出错误信息 loggerfataldata1data2 输出严重错误信息可以是任意类型参数数量可以是任意个其中普通文本在输出的时候会按照原样输出而其他的各个输出接口都会在日志内容前面附加上当前时间和日志类型 例如你调用loggererrorFail to transport the player 日志输出的结果是log20210521 194103 Error Fail to transport the player其他的一些设置项除此之外还有其他的一些设置项用来改变输出日志的格式设置自定义日志消息标头loggersetTitletitle设置的自定义标头「标头」为日志输出条目开头的文字用来直观地区分日志的输出源。 默认情况下消息标头默认为空即输出时没有标头。例如设置自定义标头为loggersetTitleLeviLamina 则在接下来的日志输出将变为形如log200526 ERROR LeviLamina Fail to transport the player统一修改日志输出等级loggersetLogLevellevel日志输出等级统一重设各种输出方向的日志输出等级 脚本引擎 通用脚本接口文档 这里提供了一些常用的 辅助功能 如插件注册、输出信息和异步接口等他们让你开发脚本变得更加容易而自然避免了很多无谓的细节问题的纠缠。 脚本辅助 API下面这些API为脚本增加了必要的辅助接口输出信息到控制台logdata1data2可以是任意类型参数数量可以是任意个输出带颜色文本这是楼上那位的升级版没错它支持彩色输出colorLogcolordata1data2此行输出的颜色代码示例和效果如下图待输出的变量或者数据 可以是任意类型参数数量可以是任意个效果展示ColorLogExampleimgColorLogpng异步输出此函数将输出请求发出后即刻返回避免同步读写造成的阻塞时间 底层有锁保护不同的fastLog之间不会出现串字符现象fastLogdata1data2待输出的变量或者数据 可以是任意类型参数数量可以是任意个推迟一段时间执行函数setTimeoutfuncmsec待执行的函数推迟执行的时间毫秒推迟一段时间执行代码段evalsetTimeoutcodemsec待执行的代码段推迟执行的时间毫秒设置周期执行函数setIntervalfuncmsec待执行的函数执行间隔周期毫秒设置周期执行代码段evalsetIntervalcodemsec待执行的代码段执行间隔周期毫秒取消延时 周期执行项clearIntervaltaskid由前几个函数返回的任务ID 国际化 API随着我们的社区越来越大语言成为了各个国家的用户和玩家之间交流的障碍。为了解决这个问题我们提供了I18nAPI并鼓励插件创作者使用国际化接口。加载翻译数据i18nloadpath defaultLocaleName defaultLangData翻译数据所在的文件1目录2默认的语言名称形如zhCN或en如果没有提供目标语言给i18ntr或i18nget的翻译这个参数将被使用 若传入空字符串则默认跟随系统语言该参数将用于补全或创建翻译文件形如jslocaleName src translationzhCN abcd114514 1919810src 源1 文件必须为JSON格式且文件内容应类似jsonlocaleName src translationzhCN abcd114514 1919810src 源2 请在路径的末尾加上路径分隔符或。目录内容应类似 LOCALEnamejsonDir enjson zhCNjson其中的每个文件内容都应类似jsonacbd translationuse nested src translation114514 1919810 heng heng aaaaaaaaaaaaaaaaaaaaaaaaaa 此处的ID为usenested114514ab The ID of this will be usenested114514bbr获取文本的指定语言翻译i18ngetkeylocaleName文本或ID目标语言默认为i18nload时传入的defaultLocaleNamebr使用指定语言翻译文本并格式化i18ntrllocaleName key 目标语言文本或ID格式化参数br使用默认语言翻译文本并格式化i18ntrkey 文本或ID格式化参数br完整样例jsi18nloadpluginsfeaturellsei18ntestlanguagejson zhCN zhCN 1 0 namedargfloat2 namedarg2f 测试 1 0 namedargfloat2 namedarg2f a b 测试2 a bwelcome Hi 欢迎来到服务器en welcome Hi Welcome to the SERVERLLSEPlayerprototypesendText LLSEPLayerprototypesendTextLLSEPlayerprototypesendText function let args Arrayfromargumentslet text argsshiftplsendTexti18ntrlthislangCode text argsloggerinfotr1 0 namedargfloat2 namedarg2f string0 1 namedarg 11451419 Named arguments should be object Out 测试 1 string0 namedargfloat2 11451loggerinfotr a b arg0 arg1 a 114514b 1919810mclistenonJoin pl plsendTextwelcome plrealName脚本引擎 系统功能接口文档 这里提供了对接 底层系统功能 的接口包括操作文件系统、访问网络等对插件开发来说实现与系统底层接口的互通是重要的扩展大大增强了插件开发的灵活性。 简单文件读写 API下面这些API提供了简单读写文件的接口为偶尔读取和写入文件提供方便。 脚本引擎使用文件类 File 来封装文件相关操作 如果需要频繁地操作文件请使用下方的文件类以提高性能 注所有文本相关的操作均使用UTF8编码。 读入文件的所有内容FilereadFrompath目标文件的路径相对路径以BDS根目录为基准向指定文件写入内容FilewriteTopathtext目标文件的路径相对路径以BDS根目录为基准要写入的内容 注若文件不存在会自动创建若存在则会先将其清空再写入向指定文件追加一行FilewriteLinepathtext目标文件的路径相对路径以BDS根目录为基准要写入的内容 文件对象 API在脚本引擎中使用「文件对象」来操作和读写某一个特定的文件。创建一个新的文件对象JavaScript new FilepathmodeisBinary Lua FilepathmodeisBinary想要打开的文件路径文件的打开模式可选参数是否以二进制模式打开文件默认为false 普通模式下文件读写过程中换行符将会被按本地格式转换。如果你使用二进制模式打开文件表明此文件并非普通的文本格式这些自动转换将不会发生。文件的打开模式有如下可选项 打开模式 表示的含义 fileReadMode 准备读取文件内容 fileWriteMode 准备写入文件。如果文件已存在会被清空 fileAppendMode 准备写入文件。之后写入的任何内容都将会被追加到文件最后 当使用ReadMode和WriteMode时可以使用seekTo手动移动文件指针位置 如果给出路径的文件存在会直接打开那个已存在的文件如果文件不存在会自动创建新的文件。如果打开的路径中有部分目录不存在接口将会自动创建目录。在打开文件之后就可以使用下述文件对象的接口来读写文件。文件对象 属性每一个文件对象都包含一些固定的对象属性。对于某个特定的文件对象fi有以下这些属性 属性 含义 类型 fipath 当前文件路径 String fiabsolutePath 当前文件的绝对路径 String fisize 当前文件大小 Integer 这些对象属性都是只读的无法被修改文件对象 函数每一个文件对象都包含一些可以执行的成员函数成员方法。对于某个特定的文件对象fi可以通过以下这些函数对这个文件进行一些操作同步读写使用同步读写接口时需要注意如果文件过大或者读写内容过多消耗时间过长可能造成游戏卡顿 如果读写内容不多使用同步接口有更好的开发体验 如果内容较多可以使用后面的异步读写接口从文件读取文本 二进制数据fireadSynccnt要读取的字符数 字节数从当前文件指针处开始读取。如果文件以二进制模式打开则返回ByteBuffer否则返回String从文件读取一行文本fireadLineSync 注意字符串尾部的换行符要自行处理从文件读取所有内容fireadAllSync从当前文件指针处开始读取一直读取到文件末尾为止。 如果文件以二进制模式打开则返回ByteBuffer否则返回String写入文本 二进制数据到文件fiwriteSyncstr要写入的内容如果文件以二进制模式打开传入的参数将被按照二进制字节写入否则将按照普通文本写入写入一行文本到文件fiwriteLineSyncstr要写入的内容此函数执行时将在字符串尾自动添加换行符异步读写在数据量较大耗费时间较长时建议使用异步读写接口以减少对服务器的影响。从文件读取文本 二进制数据异步fireadcntcallback要读取的字符数 字节数获取结果的回调函数注参数callback的回调函数原型functionresult 读取到的文本 二进制数据 如 result 为 Null 则表示读取失败从当前文件指针处开始读取。如果文件以二进制模式打开则返回ByteBuffer否则返回String从文件读取一行文本异步fireadLinecallback获取结果的回调函数注参数callback的回调函数原型functionresult 读取到的文本 注意字符串尾部的换行符要自行处理从文件读取所有内容异步fireadAllcallback获取结果的回调函数注参数callback的回调函数原型functionresult 读取到的文本 二进制数据 如 result 为 Null 则表示读取失败从当前文件指针处开始读取一直读取到文件末尾为止。 如果文件以二进制模式打开则返回ByteBuffer否则返回String写入文本 二进制数据到文件异步fiwritestrcallback要写入的内容可选参数获取结果的回调函数如果文件以二进制模式打开请传入一个ByteBuffer否则需要传入String注参数callback的回调函数原型functionresult 是否写入成功写入一行文本到文件异步fiwriteLinestrcallback要写入的内容可选参数获取结果的回调函数注参数callback的回调函数原型functionresult 是否写入成功 此函数执行时将在字符串尾自动添加换行符其他通用接口除了上述的读写接口之外这里还提供了其他操作文件对象的通用接口移动文件指针fiseekToposisRelative文件指针要移动到的位置是否是相对当前文件指针位置移动如果isRelative为truepos表示相对当前位置移动正数为向后移动负数为向前移动 如果isRelative为falsepos表示相对文件开头移动为0或正数。如果为1表示移动到文件末尾设定文件大小fisetSizesize要设定的目标大小设定的新大小可以大于文件的当前大小。 如果设定的新大小小于文件的当前大小原文件将被截断。关闭文件ficlose文件关闭后严禁再次使用文件指针是否位于文件尾fiisEOF刷新文件缓冲区fiflush获取错误码fierrorCode如果在上述接口使用中遇到了失败可以从这里获取上一个错误码清除错误状态ficlear如果在上述接口使用中遇到了失败在获取错误码完成之后使用此函数清除错误状态以继续正常使用文件对象 目录与文件 API下面这些API提供了操作文件、目录等与文件系统互动的接口 注所有传入函数的相对路径都以BDS根目录为基准。 创建文件夹 FilecreateDirdir Filemkdirdir目标文件夹的路径 可以直接创建多层不需要逐层创建删除文件 文件夹 Filedeletepath目标文件 文件夹的路径判断文件 文件夹是否存在 Fileexistspath目标文件 文件夹的路径复制文件 文件夹到指定位置 Filecopyfromto源文件 文件夹的路径目标文件 文件夹的位置移动文件 文件夹到指定位置 Filemovefromto源文件 文件夹的路径目标文件 文件夹的位置重命名指定文件 文件夹 Filerenamefromto文件 文件夹的旧名字新名字获取指定文件的大小FilegetFileSizepath所操作的文件路径如果传入的路径位置是一个文件夹则返回1判断指定路径是否是文件夹FilecheckIsDirpath所判断的路径如果目标路径不存在同样将返回false列出指定文件夹下的所有文件 文件夹FilegetFilesListdir文件夹路径 网络接口 API下面这些API为脚本提供了基本的网络接口。 如果有更复杂的需求可以使用各自语言平台的网络库来完成任务 目录发送一个异步HTTPs Get请求 networkhttpGeturlheadercallback请求的目标地址包括 Get 请求附带的参数请求头包括 Get 请求Request header 当请求返回时执行的回调函数用于回传HTTPs响应结果。注参数callback的回调函数原型functionstatusresult 返回的HTTPs响应码如200代表请求成功返回的具体数据如果请求执行失败status值将为 1发送一个异步HTTPs Post请求 networkhttpPosturlheaderdatatypecallback请求的目标地址请求头包括 Post 请求Request header 发送的数据发送的 Post 数据类型形如 textplain applicationxwwwformurlencoded 等当请求返回时执行的回调函数用于回传HTTPs响应结果。注参数callback的回调函数原型functionstatusresult 返回的HTTPs响应码如200代表请求成功返回的具体数据如果请求执行失败status值将为 1 WebSocket 客户端对象 API在脚本引擎中使用「WebSocket 对象」来操作某个 WebSocket 客户端的连接和工作创建一个新的WebSocket 客户端对象JavaScript new WSClient Lua WSClientWebSocket 客户端对象 属性每一个WS客户端对象都包含一些固定的对象属性。对于某个特定的文件对象wsc有以下这些属性 属性 含义 类型 wscstatus 当前的连接状态 Enum 这些对象属性都是只读的无法被修改其中wscstatus 枚举有如下几种情况wscOpen 处于正常连接中 wscClosing 正在断开连接 wscClosed 未连接 WebSocket 客户端对象 函数每一个WS客户端对象都包含一些可以执行的成员函数成员方法。对于某个特定的文件对象wsc可以通过以下这些函数对这个客户端进行一些操作创建连接wscconnecttarget要连接的目标地址形如wshostnameportpathpathqueryvalue异步创建连接wscconnectAsynctargetcallback要连接的目标地址形如wshostnameportpathpathqueryvalue当连接成功或者失败时执行的回调函数。注参数callback的回调函数原型functionsuccess WebSocket 连接是否成功发送文本 二进制消息wscsendmsg要发送的文本 二进制数据如果传入的参数类型是String会按照文本发送如果是ByteBuffer将按照二进制数据发送监听WebSocket事件在WS工作的过程中当收到消息或发生错误时需要对相关信息进行处理。这里给出了监听事件的接口wsclisteneventcallback要监听的事件名见下方监听事件列表注册的监听函数函数相关参数见下 当指定的事件发生时脚本引擎会调用你给出的监听函数并传入相应的参数监听事件列表functionmsg收到的文本消息functiondata收到的二进制消息functionmsg错误的提示信息functioncode错误码关闭连接wscclose在处于关闭状态时请勿继续使用此客户端对象强制断开连接wscshutdown在处于关闭状态时请勿继续使用此客户端对象获取错误码wscerrorCode如果在上述接口使用中遇到了失败可以从这里获取上一个错误码 Http 服务端对象 API脚本引擎提供了简易的Http服务端服务可以用于Webhook等数据传输量较小的Web服务。 如果您想搭建网站更推荐使用老牌Web服务软件如Apache Nginx等。创建一个新的服务器对象JavaScript new HttpServer Lua HttpServer监听 Get 请求svronGetpath callback请求目录以开头可以包含正则表达式。如 test回调函数在收到符合path的GET请求回调监听 Put 请求svronPutpath callback请求目录以开头可以包含正则表达式。如 test回调函数在收到符合path的PUT请求回调监听 Post 请求svronPostpath callback请求目录以开头可以包含正则表达式。如 test回调函数在收到符合path的POST请求回调监听 Patch 请求svronPatchpath callback请求目录以开头可以包含正则表达式。如 test回调函数在收到符合path的PATCH请求回调监听 Delete 请求svronDeletepath callback请求目录以开头可以包含正则表达式。如 test回调函数在收到符合path的DELETE请求回调监听 Options 请求svronOptionspath callback请求目录以开头可以包含正则表达式。如 test回调函数在收到符合path的OPTIONS请求回调监听请求 说明请注意请求监听是有优先级的。 如果有多个路径同时满足正则表达式则选择先定义的路径。 例如 jssvronGettest123 req res reswritetestonGettest req res reswriteget testonGettestfoo req res reswritebar 请求 test123 时第一个回调函数将被调用 而请求 testfoo 时第二个回调函数将被调用尽管第三个回调函数的路径更匹配监听 PreRouting 预路由事件svronPreRoutingcallback回调函数在收到请求时调用。在回调函数中可以修改响应如果返回false则不会继续路由至对应路径的回调函数但仍然会触发PostRouting事件。监听 PostRouting 后路由事件svronPostRoutingcallback回调函数在对应目录的回调函数或PreRouting事件执行完毕后调用在回调函数中可以修改响应监听 Error 错误事件svronErrorcallback回调函数在错误状态码 400时调用监听 Exception 异常事件svronExceptioncallback回调函数在handler中有抛出异常时调用参数3为异常信息监听端口并开启服务器svrlistenaddr port svrstartAtaddr port监听地址可以是IP地址或域名监听端口停止服务器svrstop获取服务器是否正在运行svrisRunningHttp 请求对象 APIHttp请求对象 属性 属性 含义 类型 例 reqmethod 请求方法 String GET reqpath 请求路径 String 233 reqquery 请求查询参数 Object a b c d e reqparams 请求查询参数同上 Object a b c d e reqheaders 请求头 Object a b c d e reqbody 请求内容 String awa reqremoteAddr 请求源地址 String 114514191 reqremotePort 请求源端口 Number 11451 reqversion 请求版本 String HTTP11 reqmatches 请求路径正则匹配结果 Array test11 11 这些对象属性都是只读的无法被修改并且只能在请求回调函数中使用理论上复制到外部也可以但不推荐。 1 reqmatches0 为原始文本其后面的元素才是匹配结果2 reqheaderName 为数组而不是字符串1 kv1kv2k1v1 k v1 v2 k1 v12 test testll233 testll233 ll 233获取指定请求头的值reqgetHeadername请求头名称Http 响应对象 APIHttp响应对象 属性 属性 含义 类型 例 resstatus 响应状态码 Number 200 resheaders 响应头 Object a b c d e resbody 响应内容 String awa resversion 响应版本 String HTTP11 resreason 错误原因 String OK 这些属性可以修改且应当被修改但只有在回调函数中修改才有效获取指定响应头的值reqgetHeadername响应头名称设置指定响应头的值reqsetHeadername value响应头名称响应头值写入响应内容reswritecontent1 content2 响应内容Http API 样例jslet server new HttpServerserveronGethello req resp loggerinfohttpservertest run onGet Received a request from reqremoteAddr reqremotePort for reqpathrespwritehtmlbodywriteh1It worksh1writebrwritepRequest Headers JSONstringifyreqheaders null 4 pwritepRequest Body reqbody pwritepYour Address reqremoteAddr reqremotePort pwritepHTTP Version reqversion pwritepMethod reqmethod pwritepPath reqpath pwritepParsed Query JSONstringifyreqquery null 4 pwritepPath Regex Matches JSONstringifyreqmatches pwritebodyhtmlrespstatus 200respreason OKrespsetHeaderContentType texthtmlonGet404 req resp respstatus 404respreason Not FoundrespwriteNot FoundonGettestredirect req resp httpsdevelopermozillaorgzhCNdocsWebHTTPRedirectionsrespstatus 301respreason Moved PermanentlyrespsetHeaderLocation httpsgithubcomonGet req resp respwriteHello World reqmatchesonPreRoutingreq resp loggerinfohttpservertest run onPreRouting respbodylength respbodylengthif reqpath testprerouting respbody Hello Worldrespstatus 200respreason OKreturn falseonPostRoutingreq resp loggerinfohttpservertest run onPostRouting respbodylength respbodylengthonErrorreq resp respwritenonError calledlistenthislistenaddress thislistenportloggerinfohttpservertest run Server listening on thislistenaddress thislistenport请查看 UnitTesthttpsgithubcomLiteLDevLiteLoaderBDSv2blobv2maintestUnitTestjs 系统调用 API下面这些API提供了执行一些系统调用的接口调用shell执行指定系统命令systemcmdcmdcallbacktimeLimit执行的系统命令shell进程结束之后返回数据使用的回调函数可选参数命令运行的最长时限单位为毫秒 默认为1即不限制运行时间注参数callback的回调函数原型functionexitcodeoutput shell退出码标准输出和标准错误输出的内容注意这里执行的不是MC命令系统的命令 此函数异步工作不会等待系统执行完命令后再返回而是由引擎自动调用给出的回调函数来返回结果运行指定位置程序systemnewProcessprocesscallbacktimeLimit运行的程序路径与命令行参数程序进程结束之后返回数据使用的回调函数可选参数程序进程运行的最长时限单位为毫秒 默认为1即不限制运行时间注参数callback的回调函数原型functionexitcodeoutput 程序进程退出码程序标准输出和标准错误输出的内容此函数异步工作不会等待系统执行完命令后再返回而是由引擎自动调用给出的回调函数来返回结果 获取系统信息 API下面这些API提供了获取必要的系统信息的接口获取当前时间字符串 systemgetTimeStr形如20210403 191501获取当前的时间对象systemgetTimeObj 成员 含义 类型 tmY 年份数值4位 Integer tmM 月份数值 Integer tmD 天数数值 Integer tmh 小时数值24小时制 Integer tmm 分钟数值 Integer tms 秒数值 Integer tmms 毫秒数值 Integer 随机生成一个 GUID 字符串systemrandomGuid 常见问题这个项目的目的是什么该项目的目的是在 LeviLamina 上运行 LLSE 插件。这个项目支持所有 LLSE 插件吗几乎支持所有LLSE插件但由于事件触发时机的差异等原因部分插件可能无法正常工作。这个项目会维持多久只要我们维护者有能力、有时间维护这个项目就会一直维护下去。LegacyScriptEngine一个用于在 LeviLamina 上运行 LLSE 插件的插件引擎安装 warning在安装Python引擎之前你需要先安装Python。下面是一份LSE版本和需要的Python版本的列表。 LSE 版本 Python 版本 0162 31210 090 0162 3128 090 31011 服务端要安装特定的引擎您可以使用以下命令shelllip install githubcomLiteLDevLegacyScriptEnginelualip install githubcomLiteLDevLegacyScriptEnginequickjslip install githubcomLiteLDevLegacyScriptEnginenodejslip install githubcomLiteLDevLegacyScriptEnginepython对于0100之前的版本可以使用以下命令shelllip install gitlevimcorgLiteLDevlegacyscriptenginelua版本lip install gitlevimcorgLiteLDevlegacyscriptenginequickjs版本lip install gitlevimcorgLiteLDevlegacyscriptenginenodejs版本lip install gitlevimcorgLiteLDevlegacyscriptenginepython版本可以在releaseshttpsgithubcomLiteLDevLegacyScriptEnginereleases中找到版本号。客户端要安装特定的引擎您可以使用以下命令shelllip install githubcomLiteLDevLegacyScriptEngineclientlualip install githubcomLiteLDevLegacyScriptEngineclientquickjslip install githubcomLiteLDevLegacyScriptEngineclientnodejslip install githubcomLiteLDevLegacyScriptEngineclientpython要安装特定版本需要在命令最后加上版本号例如shelllip install githubcomLiteLDevLegacyScriptEngineclientlua0170rc2lip install githubcomLiteLDevLegacyScriptEngineclientquickjs0170rc2lip install githubcomLiteLDevLegacyScriptEngineclientnodejs0170rc2lip install githubcomLiteLDevLegacyScriptEngineclientpython0170rc2使用如需获取插件开发 API 提示库和脚手架工具请访问 legacyscriptengineapihttpsgithubcomLiteLDevlegacyscriptengineapi 仓库1 直接将 LLSE 插件放在 plugins 中2 运行服务器然后插件将自动迁移到 LeviLamina 插件清单中3 重启服务器后插件就会被加载贡献如果您有任何问题请开启一个 issue 来讨论 在这里httpscrowdincomprojectlegacyscriptengine帮助我们完善翻译 欢迎 PR许可GPL30only LiteLDev创造你的首个脚本插件本指南旨在展示创建你的第一个插件的非常简单和直接的过程以及在考虑做什么和如何做时的一些最佳做法。建议有使用JavaScript的经验但不是必须的。JavaScript是一种对初学者非常友好的语言所以不要被淹没了先决条件在开发你的第一个插件之前我们需要设置你的开发环境。你用来编程的软件由你自己选择但建议使用可信和可靠的软件。你还需要建立一个干净的LeviLamina安装关于如何安装LeviLamina的细节可以在这里httpslaminalevimcorgzhinstall找到。这个服务器将被用来测试你的插件。有了你的开发环境并完成了服务器的安装你就可以开始了我现在该做什么开发一个脚本插件首先要创建你的插件文件。这个文件应该命名为 LLMyPluginjs将 MyPlugin替换为你想要的插件名称。它应该被放在你的服务器安装的插件文件夹中。有些开发环境会允许你创建一个新文件并选择一个位置而其他开发环境则允许你在点击 另存为 后才选择。这可能会使一些开发者感到困惑因为ll应该是未定义的。然而这个文件将被LeviLamina ScriptX引擎所利用。ll将在脚本运行时自动包含。这与你看到的任何其他没有定义的变量类的引用是一样的。现在我们已经创建了我们的js文件并注册了插件我们要做的就是创建一个事件监听器。我们通过使用mc来实现。jsmclistenonJoin player logplayername已经加入服务器。 参考资料 事件监听文档apisEventAPIListenzhmd为了测试你的插件只需启动服务器服务器应该能够识别你的插件并成功加载它。LeviLamina控制台将记录您创建的任何日志以及您的插件或API失败时的任何错误。开发时的迭代很重要。经常测试每一步都要确保当问题出现时你清楚地知道你改变了什么并能想出解决方案来解决它。你可以引用mc类以及其他特殊的类和构造函数。mc类是你的插件的面包和黄油将允许你做很多很酷的事情。游戏内容接口有所有的方法和属性供你使用。 参考游戏元素接口文档apisGameAPIBasiczhmd例如我们可以使用玩家对象并直接对其采取行动以发送信息操纵玩家。jsmclistenonJoin player logplayername已经加入服务器。。playersendToast欢迎 感谢您游玩本服我们可以引用玩家对象的属性并使用它来执行其他动作。jsmclistenonJoin player logplayername已经加入服务器。。playersendToast欢迎 感谢您游玩本服let loginReward mcnewItemminecraftdiamond 1mcspawnItemloginReward playerpos。这给我们带来了最后的考虑。在制作插件时尽量想一些简单的、自我封闭的东西。每个开发者都想建立一个具有大量功能的大型插件但这样的项目很容易被放弃因为它们从未真正完成。做一系列有特定目的的小插件。为这些插件添加功能以实现配置和定制。找到你希望游戏拥有的功能或事物并使用LeviLamina中的方法来实现它们。使用LeviLamina的API确实有无限可能。如果您在开发过程中遇到任何问题可以通过加入LeviLaminahttpsgithubcomLiteLDevLeviLamina的相关交流群、在LegacyScriptEngine的Github仓库上开立一个问题来回答您的问题、意见或担忧。
diff --git a/docs/tutorials/integrated_with_ai_agents.md b/docs/tutorials/integrated_with_ai_agents.md
new file mode 100644
index 00000000..0bd50bbd
--- /dev/null
+++ b/docs/tutorials/integrated_with_ai_agents.md
@@ -0,0 +1,31 @@
+# AI Agents Integration
+
+> This guide aims to demonstrate how to use the `llms.txt` file to bring intelligent interaction capabilities to AI models.
+
+---
+
+## Prerequisites
+
+- It is recommended to use **VSCode** or **Atom** as the code editor
+- A model that supports context windows
+
+---
+
+## What Should I Do Now?
+
+### 1. Add `llms.txt` to the Context Window
+
+[⬇️ Download](https://github.com/LiteLDev/LegacyScriptEngine/raw/refs/heads/develop/llms.txt)
+
+Directly copy and paste the content of the `llms.txt` file into the AI model's conversation context, or upload the file in an interface that supports file uploads.
+
+### 2. Write Plugins
+
+Use the following prompt template to have the AI generate plugin code for you:
+
+```text
+Refer to the LegacyScriptEngine documentation and use JavaScript to write a plugin for LegacyScriptEngine.  
+Please help me implement the following functionality:
+
+[Please describe the specific details of the functionality you need to implement here]
+```
\ No newline at end of file
diff --git a/docs/tutorials/integrated_with_ai_agents.zh.md b/docs/tutorials/integrated_with_ai_agents.zh.md
new file mode 100644
index 00000000..a82440b4
--- /dev/null
+++ b/docs/tutorials/integrated_with_ai_agents.zh.md
@@ -0,0 +1,31 @@
+# AI Agents集成
+
+> 本指南旨在展示如何使用 `llms.txt` 文件，为AI模型带来智能交互能力。
+
+---
+
+## 先决条件
+
+- 建议使用 **VSCode** 或 **Atom** 作为代码编辑器
+- 支持上下文窗口的模型
+
+---
+
+## 我现在该做什么？
+
+### 1. 将 `llm.txt` 添加到上下文窗口
+
+[⬇️下载](https://github.com/LiteLDev/LegacyScriptEngine/raw/refs/heads/develop/llms.txt)
+
+直接将 `llm.txt` 文件内容复制粘贴到AI模型的对话上下文中，或在支持文件上传的界面中上传该文件。
+
+### 2. 编写插件
+
+使用以下提示词模板，让AI为你生成插件代码：
+
+```text
+参考LegacyScriptEngine文档，使用JavaScript编写适用于LegacyScriptEngine的插件。
+请帮我实现以下功能：
+
+[请在此处描述您需要实现的功能的具体细节]
+```
\ No newline at end of file