教程:编写脚本API/开始之前

来自Minecraft基岩版开发Wiki
开始之前
系列教程
所属系列
编写脚本API
难度
初级
前置知识
适用版本
≥ 1.20.30
所需软件

引言[编辑]

脚本API（Script API）是Minecraft国际版中的一个脚本系统，可在附加包中实现脚本运算。

脚本API支持使用JavaScript语言（以下简称JS）编写，因此其灵活性要远大于数据驱动，可为附加包的创作提供更多可能，但脚本API无法取代数据驱动的底层注册与定义功能，例如添加方块、实体、物品等内容。在附加包的实际开发过程中，脚本API可以弥补数据驱动在逻辑运算方面灵活性的不足，从而实现更复杂的效果，而且可以在一定程度上减小附加包编写过程中的繁琐程度。同时，脚本API与Molang的对接也可以使数据驱动的灵活性更进一层。

本教程将初步帮助您了解脚本API，并完成初步的打包调试。

开始[编辑]

脚本API 本质上说不应该属于行为或资源包，但我们将它归类到行为包中。在清单文件中，我们可以管理脚本api的一些基本内容，以下提供一个范例: 

{
  "format_version": 2,
  "header": {
    "name": "示例",
    "description": "wiki",
    "uuid": "0e6bc13f-4fab-463f-bf10-a8be2ef591f6",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 50]
  },
  "modules": [
    {
      "type": "script",
      "language": "javascript",
      "uuid": "7807f855-db55-4878-b4ad-e5701f1cd98d",
      "entry": "scripts/MAIN.js",
      "version": [1, 0, 0]
    },
    {
      "description": "使游戏能识别此包为行为包",
      "type": "data",
      "uuid": "b24cd5fc-c2cc-403e-92ac-a63ffa27be77",
      "version": [1, 0, 0]
    }
  ],
  "capabilities": ["script_eval"],
  "dependencies": [
    {
      "module_name": "@minecraft/server",
      "version": "1.9.0"
    },
    {
      "module_name": "@minecraft/server-ui",
      "version": "1.2.0-beta"
    }
  ]
}

我们来简单观察一下这个 清单文件 。

首先，在 modules 中，我们看到了下面的内容: 

{
  "type": "script",
  "language": "javascript",
  "uuid": "7807f855-db55-4878-b4ad-e5701f1cd98d",
  "entry": "scripts/JSMAIN.js",
  "version": [1, 0, 0]
}

先看 type ，这是模块的类型，script 表明这这个行为包可以使用脚本API，这是一切的基础，没有它，我们将无法正常地使用脚本API。

language 表明脚本api使用的语言，指的是编程语言(如Python)，目前脚本api只能使用Js，所以这个关键字对应的值便是 javascript。

entry 指的是脚本api的入口文件，当脚本api开始运行时，会去执行入口文件，要注意的是:

  • 入口文件只能有一个，它的位置参考是基于清单文件的，为了方便，我们将所有的脚本api文件存放于 scripts 文件夹中。
  • 并不是说脚本api只能运行一个文件，通过在入口文件中利用 export 关键字等进行引用，可以执行其他文件的内容。

聪明的你想必也观察到了，下面还有一个 模块 ，也就是行为包模块(data)，为什么要在这里放这个呢，难道是脚本api必须要基于这个进行吗?答案是否定的。脚本api只需要第1个模块便可以运行，不必再添加更多的模块，但是添加它有很多的好处:

  • 将脚本api打包成 .mcpack 并导入时，如果有行为包模块，它便能成功的被当做行为包正常导入，没有的话只会返回一条导入失败的错误提示
  • 使用行为包模块的话就可以使自定义物品一类能与脚本更方便的互动，而不是打包成两个包。
  • 似乎在只拥有脚本api模块的情况下，不能添加资源包依赖，而拥有了行为包模块便可以。

这便是 modules 中有关 脚本api 的内容。

继续往下我们会看见 capabilities 关键字。脚本api本身不允许使用 eval() 和 Function()，当像上方示例一样，便可使用。如果您没有使用它们的需要，便可以删除它。

dependencies 是可以使用的脚本api的模块，请注意，你不应该把它放在模块中。脚本api可以使用很多模块 @minecraft/server 等，它们拥有各种各样的能力，我们在接下来的教程中会讲到。

接下来我们就可以在 行为包/scripts/ 路径下创建 JSMAIN.js 文件进行美妙的脚本api编写了。

基本概念[编辑]

下面介绍有关脚本api的基本概念，包括一些专有名词，了解它们可以更好的帮助接下来的学习:

看门狗[编辑]

Watchdog是脚本api的性能系统，默认情况下在启用，它拥有强大的能力，用于保护脚本api和世界存档。

看门狗会有以下操作:

操作 注意
监听运行缓慢的脚本 看本狗会监听运行缓慢的脚本，当打开了 开发者UI (日志ui)后，您就会看到它发送的警告，同时警报中还会附带运行的延迟(毫秒级)，默认为2毫秒。
监听脚本运行峰值 当脚本运行达到峰值时，它会发出警告
监听脚本运行挂载 当脚本无响应时，发出警告提醒。一般情况下，它会返回无响应时间(毫秒级)
脚本内存不足错误 当内存不足时，产生错误，看门狗会为您终止并保存世界，以防止存档受损，并留下日志
监听脚本的堆栈逆出 当发现无出口的调用时，终止调用(例如调用自己的函数)
监听脚本内存使用 当内存使用达到峰值或过高时，返回日志和警告
强终止错误 当发现未处理的严重异常时，返回日志和错误，并终止此脚本。这一般是由于脚本长时间无响应或发现了潜在的无限调用

在接下来的过程中，我们会详细介绍有关看门狗的内容，此仅作基本的错误参考

API[编辑]

API是两个或多个应用程序之间的一种相互或单方面的交互。脚本API是一组功能，允许我们与Minecraft进行交互。我们可以接收事件，读取块，修改实体，创建粒子等等。

TypeScript[编辑]

TypeScript是由Microsoft开发和维护的编程语言。它是JavaScript的严格语法超集，并为语言添加了可选的静态类型。TypeScript是为大型应用程序的开发而设计的，并可转换为JavaScript。由于TypeScript是JavaScript的超集，因此现有的JavaScript程序也是有效的TypeScript程序。

Typescript在为Minecraft插件开发脚本时非常有用。有一些库可以帮助开发Minecraft插件，为广播和收听事件提供智能感知和类型安全。

我们可能在其他教程中讲到这些。

引用[编辑]

1.官方文档:manifest.json
2.官方文档:脚本api

取自“https://wiki.mcbe-dev.net/w/index.php?title=Tutorial:编写脚本API/开始之前&oldid=24231”