# MCBE SAPI

## 新手上路

> 假期玩 MC 服务器，换整合包期间无聊外加开发组有需要，我本身是有了解过 JavaScript，于是就上手琢磨了下《我的世界》基岩版附加包（Add-on）的 Script API 开发。

## 开发环境部署

### 步骤 1：安装代码编辑器和调试器拓展

- 自行下载和安装 [Visual Studio Code](https://code.visualstudio.com)；

- 安装 [Minecraft Bedrock Edition Debugger](https://marketplace.visualstudio.com/items?itemName=mojang-studios.minecraft-debugger) 拓展，这是用于开发过程中对部分代码进行调试的工具。通过该拓展，可以直观的看到代码运行时的情况。
  - *（该拓展可根据自己需求选择性安装，不影响开发）*

### 步骤 2：安装 Node.js  环境

- 自行下载和安装 [Node.js](https://nodejs.org/zh-cn)。
  - 不懂安装或出问题的可查阅 [菜鸟教程 - Node.js 安装配置](https://www.runoob.com/nodejs/nodejs-install-setup.html)

### 步骤 3：新建行为包文件夹

- 在资源管理器地址栏中输入下面的路径地址，打开 Win10 MCBE 的行为包开发文件夹。该文件夹可方便开发者进行开发行为包的活动，当你修改源码后不必编译打包，只需在游戏内输入`/reload`命令即可重新加载行为包，以便测试；
  - `%localappdata%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs`

- 创建文件夹，名字随便你，这个创建的文件夹就是用来存放你开发的 Add-on 包的文件。

### 步骤 4：安装 NPM 包

- 使用 Visual Studio Code 打开新建的文件夹，按下快捷键`Ctrl + ~` 打开终端，输入以下命令即可安装开发所需的包。
  - `npm i @minecraft/server@1.4.0-beta.1.20.10-stable`
    - @minecraft/server：这部分是指定开发时所需要使用到的模块包
    - @1.4.0-beta.1.20.10-stable：这部分是该包的版本，需要与游戏版本对应！
      - 该版本号中的 1.20.10 就是对应游戏版本号
      - 请记住 1.4.0-beta 这个信息，后面要用

    - 在 [@minecraft/server - versions](https://www.npmjs.com/package/@minecraft/server?activeTab=versions) 该页面可查看到历史版本，我们只需找到与游戏版本对应的包安装即可

  - 通过该包，开发者可在编写代码的过程中看到相关函数的注解提示内容
  - *（该包可根据自己需求选择性安装，不影响开发，但是需要你有熟练的开发能力）*


### 步骤 5：配置和使用调试器

- *（若你没有安装调试器拓展可忽略本步骤）*
- 在当前文件夹下继续新建一个名为`.vscode`的文件夹；
- 进入文件夹，并新建名为`launch.json`文件，复制下面代码即可，无须任何改动；

```json
{
   	"version": "0.2.0",
    "configurations": [
        {
            "type": "minecraft-js",
            "request": "attach",
            "name": "Wait for Minecraft Debug Connections",
            "mode": "listen",
            "localRoot": "${workspaceFolder}/scripts/",
            "port": 19144
        }
    ]
}
```

- 当你需要用到调试器时，按下快捷键`F5`即可启动调试；
- 进入游戏激活本行为包后，输入`/script debugger connect localhost 19144`连接成功后，即可愉快的进行调试工作了。

## 开始上手开发

### Manifest JSON 配置文件

在行为包的主文件夹里新建行为包的清单文件`manifest.json`文件，该文件包含有关 Minecraft 识别它所需的包的所有基本信息。

在开始编写脚本前，需要在`manifest.json`文件里，写上依赖模块导入的配置信息，如下所示：

```json
"dependencies": [
    {
        "module_name": "@minecraft/server",
        "version": "1.4.0-beta"
    }
]
```

里面的`module_name`是你写脚本时需要用到的模块；`version`是该模块的版本号，需要与游戏版本对应，上面步骤 4 让你记住的 1.4.0-beta 内容此时就有用了。

如果你需要用到其他模块可按照上面的环境部署步骤 4 安装好开发包，确定好版本号，分别修改`module_name`和`version`即可。

接着，我们需要继续在这个文件里写上导入脚本的配置信息，如下所示：

```json
"modules": [
    {
        "type": "script",
        "language": "javascript",
        "uuid": "4df749f2-8fb3-2560-97a2-0c906ea84b98",
        "entry": "scripts/main.js",
        "version": [ 1, 0, 0 ]
    }
]
```

里面`uuid`是脚本模块的唯一标识符，可[在线生成UUID](https://uutool.cn/uuid/)；`entry`是脚本存放的路径，一般行为包脚本文件是存放在主文件夹的`script`目录里；`version`是该脚本的版本号；`type`和`language`是用来标识该模块类型为脚本模块。

完成以上部分配置即可进行脚本开发，更多相关配置项请自行查阅 [Addons Documentation - manifest.json - Microsoft Learn](https://learn.microsoft.com/en-us/minecraft/creator/reference/content/addonsreference/examples/addonmanifest) 文档。

### 编写第一个脚本

在`scripts/main.js`中写下如下代码，当有玩家进入游戏生成后就会触发事件，在触发的事件里，如果玩家是进入游戏并非重生，则向该玩家发送一条内容为“欢迎 玩家名 进入游戏！”的消息并且执行了一条内容为`say hello`的指令。

```javascript
import { world } from "@minecraft/server";

world.afterEvents.playerSpawn.subscribe(ev => {
    const plName = ev.player.name

    if (ev.initialSpawn) {
        ev.player.sendMessage(`欢迎 ${plName} 进入游戏！`)
        ev.player.runCommandAsync('say hello')
    }
})
```

### 测试脚本运行

完成代码编写后，我们打开游戏，创建新世界，在左侧的“实验性游戏内容”里开启“测试版 API”功能；同时在左侧的“行为包”里激活你的行为包，创造并进入游戏，你就能看见脚本运行的结果了！

**非常棒吧？**赶紧去试一下。

**至此**，以上是我新手上路时经历的一些过程，希望对您有参考帮助，有不足之处望您谅解，或可与我联系共同进步，**祝您编码愉快！**

## 折腾过程记录

按我习惯的学习思路，先是去 [脚本API - Minecraft基岩版开发Wiki](https://wiki.mcbe-dev.net/p/脚本API) 和 [Script API Reference Documentation - Microsoft Learn](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/)了解了相关知识，发现是为行为包提供的一个脚本系统。

继续深入了解，我分别从搜索引擎和 B 站大学进行了海量的相关检索，了解到大致的代码编写形式，但是我依然找不到适合我开始上手编写的非常小白的教程，大多都是功能展示和代码编写过程，根本没有给出代码编写的前置环境情况。

后面的时间里，我仍然在海量的进行检索。从原来的搜索引擎和 B 站大学拓展到了 YouTube、ChatGPT 和 Github，甚至到 MCPEDL 下载了别人写好行为包，进行解包查阅代码，结果嘛，要么是没效果要么是代码加密的。一直没得到进展，检索到的东西也是反反复复的。

当然，在这过程里，我从 YouTube 了解到一个专门开发基岩版 Add-on 的网站 [bridge IDE](https://bridge-core.app/)，为我后面的 Script API 开发奠定了基础。经过我反反复复的查阅 [Use Visual Studio Code tools to write script - Microsoft Learn](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/)，不断地踩坑，终于是部署好了我的开发环境！

踩完了基础的坑，接着就是踩写代码的坑了。不断海量检索还是反反复复的内容，如出一辙；不断地试错求最合适的解。

到了晚饭的点，心累到极致的我暂停了折腾，在群里吐槽我搞不动了。群聊过程中得到的信息我也基本上都看过了，但我还是忍不住又打开看了看，什么嘛又是一样的内容，心累的我只能无聊的仔细看了个遍；反复的看别人 Github 仓库的文件，脑海出现了一个新思路，会不会是版本问题？npm 安装的默认是 latest 的版本，于是我查阅了 [@minecraft/server](https://www.npmjs.com/package/@minecraft/server?activeTab=versions) 包的版本历史发现最近的更新竟然是 3 天前！

接着又发现每个版本的命名格式有部分跟 MC 版本号是一致的，再接着的发现证实了我的猜想，在 [minecraft-scripting-samples/ts-starter](https://github.com/microsoft/minecraft-scripting-samples/tree/main/ts-starter) 这个库的自述文件里有这么一句被引用的话，是这样说的：

> IMPORTANT:
> You may also need to update the version of Beta APIs in your `dependencies` section to match your version of Minecraft.
> Versions 1.19.40 feature `1.0.0-beta` APIs
> Versions 1.19.50, 1.19.60, and 1.19.70 feature `1.1.0-beta` APIs
> Versions 1.19.80 features `1.2.0-beta` APIs
> Versions 1.20.0 features `1.3.0-beta` APIs
> Versions 1.20.10 features `1.4.0-beta` APIs
> Versions 1.20.20 features `1.5.0-beta` APIs
> Future versions will likely require updated versions of Beta APIs.

根据这个猜想，我修改了相关的文件，重新下载了 npm 包，激活了写好的 Add-on 包进入游戏，**Oh My God！** 成功啦！！！

## 折腾总结

- 一直以来没有养成过看专业性的文档，导致我看这类文档的时候很浮躁，不够仔细；
- 自己的能力基础不扎实，以至于看不懂文档，或者说要看几十遍才能勉强了解；
- **最重要的一点**，英文不好导致有小部分时间在理解机翻的内容。
- *我还是太嫩了*