MCBE SAPI

新手上路

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

开发环境部署

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

步骤 2：安装 Node.js 环境

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

步骤 4：安装 NPM 包

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

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

开始上手开发

Manifest JSON 配置文件

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

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

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

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

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

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

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

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

完成以上部分配置即可进行脚本开发，更多相关配置项请自行查阅 Addons Documentation - manifest.json - Microsoft Learn 文档。

编写第一个脚本

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

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 和 Script API Reference Documentation - Microsoft Learn了解了相关知识，发现是为行为包提供的一个脚本系统。

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

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

当然，在这过程里，我从 YouTube 了解到一个专门开发基岩版 Add-on 的网站 bridge IDE，为我后面的 Script API 开发奠定了基础。经过我反反复复的查阅 Use Visual Studio Code tools to write script - Microsoft Learn，不断地踩坑，终于是部署好了我的开发环境！

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

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

接着又发现每个版本的命名格式有部分跟 MC 版本号是一致的，再接着的发现证实了我的猜想，在 minecraft-scripting-samples/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！ 成功啦！！！

折腾总结